From 8feaa06630a4d47965add408ac0900062fbe2255 Mon Sep 17 00:00:00 2001 From: Bogdan Gusiev Date: Tue, 19 Nov 2024 14:55:04 +0100 Subject: [PATCH] Update doc --- lib/datagrid/filters.rb | 51 +++++++++++++----------------- lib/datagrid/helper.rb | 70 +++++++++++++++++------------------------ 2 files changed, 51 insertions(+), 70 deletions(-) diff --git a/lib/datagrid/filters.rb b/lib/datagrid/filters.rb index 59ae3b5..c7fe692 100644 --- a/lib/datagrid/filters.rb +++ b/lib/datagrid/filters.rb @@ -196,35 +196,28 @@ def filter_by_name(attribute) # @param [Hash] options hash of options # @param [Proc] block proc to apply the filter # @return [Datagrid::Filters::BaseFilter] Filter definition object - # @see https://github.com/bogdan/datagrid/wiki/Filters - # - # Available options: - # - # * :header - determines the header of the filter - # * :default - the default filter value. - # Able to accept a Proc in case default should be recalculated - # * :range - if true, filter can accept two values - # that are treated as a range that will be used for filtering - # Not all of the filter types support this option. Here are the list of types that do: - # :integer, :float, :date, :datetime, :string - # * :multiple - if true multiple values can be assigned to this filter. - # If String is assigned as a filter value, it is parsed from string using a separator symbol (`,` by default). - # But you can specify a different separator as option value. Default: false. - # * :allow_nil - determines if the value can be nil - # * :allow_blank - determines if the value can be blank - # * :before - determines the position of this filter, - # by adding it before the filter passed here (when using datagrid_form_for helper) - # * :after - determines the position of this filter, - # by adding it after the filter passed here (when using datagrid_form_for helper) - # * :dummy - if true, this filter will not be applied automatically - # and will be just displayed in form. In case you may want to apply it manually. - # * :if - specify the condition when the filter can be dislayed and used. - # Accepts a block or a symbol with an instance method name - # * :unless - specify the reverse condition when the filter can be dislayed and used. - # Accepts a block or a symbol with an instance method name - # * :input_options - options passed when rendering html input tag attributes. - # Use input_options.type to control input type including textarea. - # * :label_options - options passed when rendering html label tag attributes + # @see Datagrid::Filters + # @option options [String] header Determines the header of the filter. + # @option options [Object, Proc] default The default filter value. Accepts a `Proc` to allow dynamic calculation. + # @option options [Boolean] range Whether the filter accepts two values to define a range. + # Supported by types: `:integer`, `:float`, `:date`, `:datetime`, and `:string`. + # @option options [Boolean, String] multiple If true, allows multiple values for the filter. + # Strings are parsed using a separator (default: `,`). Can accept a custom separator. Default: `false`. + # @option options [Boolean] allow_nil Whether the filter value can be `nil`. Default: `false`. + # @option options [Boolean] allow_blank Whether the filter value can be blank. Default: `false`. + # @option options [Symbol] before Specifies the position of this filter by placing it before another filter. + # 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 [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. + # Accepts a block or the name of an instance method. + # @option options [Hash] input_options Options passed to the HTML input tag for rendering attributes. + # Use `input_options[:type]` to control the input type (e.g., `textarea`). + # @option options [Hash] label_options Options passed to the HTML label tag for rendering attributes. def filter(name, type = :default, **options, &block) klass = type.is_a?(Class) ? type : FILTER_TYPES[type] raise ConfigurationError, "filter class #{type.inspect} not found" unless klass diff --git a/lib/datagrid/helper.rb b/lib/datagrid/helper.rb index 24b1edb..24c25eb 100644 --- a/lib/datagrid/helper.rb +++ b/lib/datagrid/helper.rb @@ -268,19 +268,16 @@ def datagrid_format_value(grid, column, model) # Renders html table with columns defined in grid class. # In the most common used you need to pass paginated collection # to datagrid table because datagrid do not have pagination compatibilities: - # Supported options: - # - # * :html - hash of attributes for tag - # * :order - If false do not generate ordering controlls. - # Default: true. - # * :columns - Array of column names to display. - # Used in case when same grid class is used in different places - # and needs different columns. Default: all defined columns. - # * :partials - Path for partials lookup. - # Default: 'datagrid'. # @param grid [Datagrid] grid object # @param assets [Array] objects from grid scope # @param [Hash{Symbol => Object}] options HTML attributes to be passed to `
` tag + # @option options [Hash] html A hash of attributes for the `
` tag. + # @option options [Boolean] order Whether to generate ordering controls. + # If set to `false`, ordering controls are not generated. Default: `true`. + # @option options [Array] columns An array of column names to display. + # Use this when the same grid class is used in different contexts and requires different columns. + # Default: all defined columns. + # @option options [String] partials The path for partials lookup. Default: `'datagrid'`. # @return [String] table tag HTML markup # @example # assets = grid.assets.page(params[:page]) @@ -291,15 +288,13 @@ def datagrid_table(grid, assets = grid.assets, **options) # Renders HTML table header for given grid instance using columns defined in it # - # Supported options: - # - # * :order - display ordering controls built-in into header - # Default: true - # * :columns - Array of column names to display. - # Used in case when same grid class is used in different places - # and needs different columns. Default: all defined columns. - # * :partials - Path for partials lookup. - # Default: 'datagrid'. + # @option options [Boolean] order Whether to display ordering controls built into the header. + # Default: `true`. + # @option options [Array] columns An array of column names to display. + # Use this when the same grid class is used in different contexts and requires different columns. + # Default: all defined columns. + # @option options [String] partials The path for partials lookup. + # Default: `'datagrid'`. # @param grid [Datagrid] grid object # @param [Hash] options # @return [String] HTML table header tag markup @@ -310,19 +305,16 @@ def datagrid_header(grid, options = {}) # Renders HTML table rows using given grid definition using columns defined in it. # Allows to provide a custom layout for each for in place with a block # - # Supported options: - # - # * :columns - Array of column names to display. - # Used in case when same grid class is used in different places - # and needs different columns. Default: all defined columns. - # * :partials - Path for partials lookup. - # Default: 'datagrid'. - # + # @option options [Array] columns An array of column names to display. + # Use this when the same grid class is used in different contexts and requires different columns. + # Default: all defined columns. + # @option options [String] partials The path for partials lookup. + # Default: `'datagrid'`. # @return [String] - # @example - # = datagrid_rows(grid) # Generic table rows Layout - # - # = datagrid_rows(grid) do |row| # Custom Layout + # @example Generic table rows Layout + # = datagrid_rows(grid) + # @example Custom Layout + # = datagrid_rows(grid) do |row| # %tr # %td= row.project_name # %td.project-status{class: row.status}= row.status @@ -331,11 +323,8 @@ def datagrid_rows(grid, assets = grid.assets, **options, &block) end # @return [String] renders ordering controls for the given column name - # - # Supported options: - # - # * :partials - Path for partials lookup. - # Default: 'datagrid'. + # @option options [String] partials The path for partials lookup. + # Default: `'datagrid'`. def datagrid_order_for(grid, column, options = {}) datagrid_renderer.order_for(grid, column, options) end @@ -361,20 +350,19 @@ def datagrid_form_for(grid, options = {}) # @param block [Proc] block with Datagrid::Helper::HtmlRow as an argument returning a HTML markup as a String # @param [Hash{Symbol => Object}] options # @return [Datagrid::Helper::HtmlRow, String] captured HTML markup if block given otherwise row object - # @example - # # Suppose that grid has first_name and last_name columns + # @example Render default layout for row + # <%= datagrid_row(grid, user, columns: [:first_name, :last_name, :actions]) %> + # @example Rendering custom layout for `first_name` and `last_name` columns # <%= datagrid_row(grid, user) do |row| %> # # # # # <% end %> - # @example + # @example Rendering custom layout passing a block # <% row = datagrid_row(grid, user) %> # First Name: <%= row.first_name %> # Last Name: <%= row.last_name %> - # @example - # <%= datagrid_row(grid, user, columns: [:first_name, :last_name, :actions]) %> def datagrid_row(grid, asset, **options, &block) datagrid_renderer.row(grid, asset, **options, &block) end
<%= row.first_name %><%= row.last_name %>