From 3558341687f4648f866cab87c8a931130e78dc7d Mon Sep 17 00:00:00 2001 From: Bogdan Gusiev Date: Tue, 19 Nov 2024 20:11:04 +0100 Subject: [PATCH] Improve docs --- README.md | 2 +- datagrid.gemspec | 2 +- lib/datagrid/columns.rb | 128 ++++++++++++++++------------------ lib/datagrid/configuration.rb | 6 +- lib/datagrid/filters.rb | 4 +- lib/datagrid/helper.rb | 11 +-- version-2/Readme.markdown | 8 +-- 7 files changed, 79 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 24fa669..19d8fd2 100644 --- a/README.md +++ b/README.md @@ -162,7 +162,7 @@ end Some formatting options are also available. Each column is sortable. -[More about columns](https://github.com/bogdan/datagrid/wiki/Columns) +[More about columns](https://rubydoc.info/gems/datagrid/Datagrid/Columns) ### Front end diff --git a/datagrid.gemspec b/datagrid.gemspec index be63ba3..419c4d1 100644 --- a/datagrid.gemspec +++ b/datagrid.gemspec @@ -28,7 +28,7 @@ Gem::Specification.new do |s| s.metadata = { "homepage_uri" => s.homepage, "bug_tracker_uri" => "#{s.homepage}/issues", - "documentation_uri" => "#{s.homepage}/wiki", + "documentation_uri" => "https://rubydoc.info/gems/datagrid", "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md", "source_code_uri" => s.homepage, "rubygems_mfa_required" => "true", diff --git a/lib/datagrid/columns.rb b/lib/datagrid/columns.rb index 8570396..795f1e7 100644 --- a/lib/datagrid/columns.rb +++ b/lib/datagrid/columns.rb @@ -2,6 +2,7 @@ require "datagrid/utils" require "active_support/core_ext/class/attribute" +require "datagrid/columns/column" module Datagrid # Defines a column to be used for displaying data in a Datagrid. @@ -199,29 +200,26 @@ module Datagrid # presenter.user.created_at # end module Columns - require "datagrid/columns/column" - - # @!method default_column_options=(value) - # @param [Hash] value default options passed to #column method call - # @return [Hash] default options passed to #column method call - # @example - # # Disable default order + # @param [Hash] value default options passed to {#column} method call + # @return [Hash] default options passed to {#column} method call + # @example Disable default order # self.default_column_options = { order: false } - # # Makes entire report HTML + # @example Makes entire report HTML # self.default_column_options = { html: true } + # @!method default_column_options=(value) - # @!method default_column_options - # @return [Hash] + # @return [Hash] default options passed to {#column} method call # @see #default_column_options= + # @!method default_column_options # @!method batch_size=(value) - # @param [Integer] value Specify a default batch size when generating CSV or just data. Default: 1000 - # @return [Integer] Specify a default batch size when generating CSV or just data. - # @example + # Specify a default batch size when generating CSV or just data. + # @param [Integer] value a batch size when generating CSV or just data. Default: 1000 + # @return [void] + # @example Set batch size to 500 # self.batch_size = 500 - # # Disable batches + # @example Disable batches # self.batch_size = nil - # # @!method batch_size # @return [Integer] @@ -253,37 +251,31 @@ def columns(*column_names, data: false, html: false) filter_columns(columns_array, *column_names, data: data, html: html) end - # Defines new datagrid column - # + # Defines a new datagrid column # @param name [Symbol] column name # @param query [String, nil] a string representing the query to select this column (supports only ActiveRecord) - # @param options [Hash{Symbol => Object}] hash of options # @param block [Block] proc to calculate a column value + # @option options [Boolean, String] html Determines if the column should be present + # in the HTML table and how it is formatted. + # @option options [String, Array] order Determines if the column can be sortable and + # specifies the ORM ordering method. + # Example: `"created_at, id"` for ActiveRecord, `[:created_at, :id]` for Mongoid. + # @option options [String] order_desc Specifies a descending order for the column + # (used when `:order` cannot be easily reversed by the ORM). + # @option options [Boolean, Proc] order_by_value Enables Ruby-level ordering for the column. + # Warning: Sorting large datasets in Ruby is not recommended. + # If `true`, Datagrid orders by the column value. + # If a block is provided, Datagrid orders by the block's return value. + # @option options [Boolean] mandatory If `true`, the column will never be hidden by the `#column_names` selection. + # @option options [Symbol] before Places the column before the specified column when determining order. + # @option options [Symbol] after Places the column after the specified column when determining order. + # @option options [Boolean, Proc] if conditions when a column is available. + # @option options [Boolean, Proc] unless conditions when a column is not available. + # @option options [Symbol, Array] preload Specifies associations + # to preload for the column within the scope. + # @option options [Hash] tag_options Specifies HTML attributes for the `` or `` of the column. + # Example: `{ class: "content-align-right", "data-group": "statistics" }`. # @return [Datagrid::Columns::Column] - # - # Available options: - # - # * html - determines if current column should be present in html table and how is it formatted - # * order - determines if this column could be sortable and how. - # The value of order is explicitly passed to ORM ordering method. - # Example: "created_at, id" for ActiveRecord, [:created_at, :id] for Mongoid - # * order_desc - determines a descending order for given column - # (only in case when :order can not be easily reversed by ORM) - # * order_by_value - used in case it is easier to perform ordering at ruby level not on database level. - # Warning: using ruby to order large datasets is very unrecommended. - # If set to true - datagrid will use column value to order by this column - # If block is given - datagrid will use value returned from block - # * mandatory - if true, column will never be hidden with #column_names selection - # * url - a proc with one argument, pass this option to easily convert the value into an URL - # * before - determines the position of this column, by adding it before the column passed here - # * after - determines the position of this column, by adding it after the column passed here - # * if - the column is shown if the reult of calling this argument is true - # * unless - the column is shown unless the reult of calling this argument is true - # * preload - spefies which associations of the scope should be preloaded for this column - # * `tag_options` - specify HTML attributes to be set for `` or `` of a column - # Example: `{ class: "content-align-right", "data-group": "statistics" }` - # - # @see https://github.com/bogdan/datagrid/wiki/Columns def column(name, query = nil, **options, &block) define_column(columns_array, name, query, **options, &block) end @@ -333,10 +325,10 @@ def format(value, &block) # Defines a model decorator that will be used to define a column value. # All column blocks will be given a decorated version of the model. # @return [void] - # @example + # @example Wrapping a model with presenter # decorate { |user| UserPresenter.new(user) } - # - # decorate { UserPresenter } # a shortcut + # @example A shortcut for doing the same + # decorate { UserPresenter } def decorate(model = nil, &block) if !model && !block raise ArgumentError, "decorate needs either a block to define decoration or a model to decorate" @@ -403,14 +395,16 @@ def assets ) end - # @param column_names [Array] list of column names if you want to limit data only to specified columns + # @param column_names [Array] list of column names + # if you want to limit data only to specified columns # @return [Array] human readable column names. See also "Localization" section def header(*column_names) data_columns(*column_names).map(&:header) end # @param asset [Object] asset from datagrid scope - # @param column_names [Array] list of column names if you want to limit data only to specified columns + # @param column_names [Array] list of column names + # if you want to limit data only to specified columns # @return [Array] column values for given asset def row_for(asset, *column_names) data_columns(*column_names).map do |column| @@ -419,7 +413,8 @@ def row_for(asset, *column_names) end # @param asset [Object] asset from datagrid scope - # @return [Hash] A mapping where keys are column names and values are column values for the given asset + # @return [Hash] A mapping where keys are column names and + # values are column values for the given asset def hash_for(asset) result = {} data_columns.each do |column| @@ -428,7 +423,8 @@ def hash_for(asset) result end - # @param column_names [Array] list of column names if you want to limit data only to specified columns + # @param column_names [Array] list of column names + # if you want to limit data only to specified columns # @return [Array>] with data for each row in datagrid assets without header def rows(*column_names) map_with_batches do |asset| @@ -436,7 +432,8 @@ def rows(*column_names) end end - # @param column_names [Array] list of column names if you want to limit data only to specified columns + # @param column_names [Array] list of column names + # if you want to limit data only to specified columns. # @return [Array>] data for each row in datagrid assets with header. def data(*column_names) rows(*column_names).unshift(header(*column_names)) @@ -514,7 +511,7 @@ def html_columns(*column_names, data: false) columns(*column_names, data: data, html: true) end - # Finds a column definition by name + # Finds a column by name # @param name [String, Symbol] column name to be found # @return [Datagrid::Columns::Column, nil] def column_by_name(name) @@ -522,17 +519,16 @@ def column_by_name(name) end # Gives ability to have a different formatting for CSV and HTML column value. - # - # @example + # @example Formating using Rails view helpers # column(:name) do |model| # format(model.name) do |value| # tag.strong(value) # end # end - # + # @example Formatting using a separated view template # column(:company) do |model| # format(model.company.name) do - # render partial: "company_with_logo", locals: {company: model.company } + # render partial: "companies/company_with_logo", locals: {company: model.company } # end # end # @return [Datagrid::Columns::Column::ResponseFormat] Format object @@ -548,18 +544,18 @@ def format(value, &block) # @param [Object] asset one of the assets from grid scope # @return [Datagrid::Columns::DataRow] an object representing a grid row. # @example - # class MyGrid - # scope { User } - # column(:id) - # column(:name) - # column(:number_of_purchases) do |user| - # user.purchases.count - # end - # end + # class MyGrid + # scope { User } + # column(:id) + # column(:name) + # column(:number_of_purchases) do |user| + # user.purchases.count + # end + # end # - # row = MyGrid.new.data_row(User.last) - # row.id # => user.id - # row.number_of_purchases # => user.purchases.count + # row = MyGrid.new.data_row(User.last) + # row.id # => user.id + # row.number_of_purchases # => user.purchases.count def data_row(asset) ::Datagrid::Columns::DataRow.new(self, asset) end diff --git a/lib/datagrid/configuration.rb b/lib/datagrid/configuration.rb index 5c64e3e..a80e8b2 100644 --- a/lib/datagrid/configuration.rb +++ b/lib/datagrid/configuration.rb @@ -25,12 +25,14 @@ def self.configure(&block) # Datagrid.configure do |config| # # Defines date formats that can be used to parse dates. # # Note: Multiple formats can be specified. The first format is used to format dates as strings, - # # while other formats are used only for parsing dates from strings (e.g., if your app supports multiple formats). + # # while other formats are used only for parsing dates + # # from strings (e.g., if your app supports multiple formats). # config.date_formats = "%m/%d/%Y", "%Y-%m-%d" # # # Defines timestamp formats that can be used to parse timestamps. # # Note: Multiple formats can be specified. The first format is used to format timestamps as strings, - # # while other formats are used only for parsing timestamps from strings (e.g., if your app supports multiple formats). + # # while other formats are used only for parsing timestamps + # # from strings (e.g., if your app supports multiple formats). # config.datetime_formats = ["%m/%d/%Y %h:%M", "%Y-%m-%d %h:%M:%s"] # end # ``` diff --git a/lib/datagrid/filters.rb b/lib/datagrid/filters.rb index 6856b77..19637c8 100644 --- a/lib/datagrid/filters.rb +++ b/lib/datagrid/filters.rb @@ -204,8 +204,8 @@ def filter_by_name(attribute) # Used with the `datagrid_form_for` helper. # @option options [Symbol] after Specifies the position of this filter by placing it after another filter. # Used with the `datagrid_form_for` helper. - # @option options [Boolean] dummy If true, the filter is not applied automatically and is only displayed in the form. - # Useful for manual application. + # @option options [Boolean] dummy If true, the filter is not applied automatically and + # is only displayed in the form. Useful for manual application. # @option options [Proc, Symbol] if Specifies a condition under which the filter is displayed and used. # Accepts a block or the name of an instance method. # @option options [Proc, Symbol] unless Specifies a condition under which the filter is NOT displayed or used. diff --git a/lib/datagrid/helper.rb b/lib/datagrid/helper.rb index dca8579..5a1bc37 100644 --- a/lib/datagrid/helper.rb +++ b/lib/datagrid/helper.rb @@ -17,7 +17,8 @@ module Datagrid # [built-in CSS](https://github.com/bogdan/datagrid/blob/master/app/assets/stylesheets/datagrid.sass). # # Datagrid includes helpers and a form builder for easy frontend generation. - # If you need a fully-featured custom GUI, create your templates manually with the help of the {Datagrid::Columns} API. + # If you need a fully-featured custom GUI, create your templates manually + # with the help of the {Datagrid::Columns} API. # # ## Controller and Routing # @@ -63,7 +64,8 @@ module Datagrid # # ### Advanced Method # - # You can use Rails built-in tools to create a form. Additionally, Datagrid provides helpers to generate input/select elements for filters: + # You can use Rails built-in tools to create a form. + # Additionally, Datagrid provides helpers to generate input/select elements for filters: # # ``` haml # - form_with model: UserGrid.new, method: :get, url: users_path do |f| @@ -360,9 +362,8 @@ def datagrid_order_for(grid, column, options = {}) # @option options [String] partials Path for form partial lookup. # Default: `'datagrid'`, which uses `app/views/datagrid/` partials. # Example: `'datagrid_admin'` uses `app/views/datagrid_admin` partials. - # @option options [Object] model The Datagrid object to be rendered. + # @option options [Datagrid::Base] model a Datagrid object to be rendered. # @option options [Hash] All options supported by Rails `form_with` helper. - # @param grid [Datagrid::Base] grid object # @param [Hash{Symbol => Object}] options # @return [String] form HTML tag markup def datagrid_form_with(**options) @@ -466,7 +467,7 @@ def _render_partial(partial_name, partials_path, locals = {}) # row = datagrid_row(grid, user) # row.class # => Datagrid::Helper::HtmlRow # row.first_name # => "Bogdan" - # row.grid # => Grid object + # row.grid # => Datagrid::Base object # row.asset # => User object # row.each do |value| # puts value diff --git a/version-2/Readme.markdown b/version-2/Readme.markdown index 50487b3..50a8e12 100644 --- a/version-2/Readme.markdown +++ b/version-2/Readme.markdown @@ -63,8 +63,6 @@ Rails [deprecates form\_for in favor of form\_with](https://guides.rubyonrails.o `datagrid_form_for` is now deprecated if favor of `datagrid_form_with`. -TODO: update the wiki - ``` ruby # V1 datagrid_form_for(@users_grid, url: users_path) @@ -184,7 +182,7 @@ and avoid collisions with other libraries: | checkboxes | datagrid-enum-checkboxes | All classes are now explicitly assinged inside datagrid partials. -[Modify built-in partials](https://github.com/bogdan/datagrid/wiki/Frontend#modifying-built-in-partials) +[Modify built-in partials](https://rubydoc.info/gems/datagrid/Datagrid/Helper#modifying-built-in-partials) if you want to change them. Diff for [built-in partials between V1 and V2](./views.diff) @@ -370,7 +368,7 @@ instead of classes for column names. * Column name `th[class], td[class]` implemented as `td[data-column], th[data-column]`. Note that the behavior change can be reverted by -[updating built-in partials](https://github.com/bogdan/datagrid/wiki/Frontend#modifying-built-in-partials). +[Modify built-in partials](https://rubydoc.info/gems/datagrid/Datagrid/Helper#modifying-built-in-partials) Version 2 makes it as easy as possible to override the defaults of the UI. ### Filters @@ -451,7 +449,7 @@ Renders: John ``` -[Modify built-in views](https://github.com/bogdan/datagrid/wiki/Frontend#modifying-built-in-partials) +[Modify built-in partials](https://rubydoc.info/gems/datagrid/Datagrid/Helper#modifying-built-in-partials) if you want to change this behavior completely. ## Use column[tag\_options]