datagrid 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4f9903c41d2efb4c914ddf949db685228644e1ba071e8e2337491e0b91e0bbd
-  data.tar.gz: 937aea06689389c091b3be16aabaa36d8c828b8a8e97f220eaad403975371c6e
+  metadata.gz: 73b5ec45b488122854f535af2e33440795923c7186f07195b1dd12c830656a83
+  data.tar.gz: 72b4cf51c6b47d6d3985bad16f0ca775b09b0770172c8ddaa67eb53091f50fb5
 SHA512:
-  metadata.gz: b3a5ef4923f03bd41bc54c2cc8ad6261f4a1e3302c4aad83a58868d539d69527a6cf838ee6efdf621fa0a47dabd023fa041773dde723f35f0feaf59e0b5effe6
-  data.tar.gz: 0a4c6aca85619ab3a71c125717d6f6f5209eafcb7a509df76afaac91e70790f199fea2ac796ebb9c05d088c8f4d40b42c16d6a49a28661ae1da7703c86c1ff92
+  metadata.gz: ebd3afee727b599bc3cfb1bb54aea656fb117edff207bfde118ef9fce36d716344ab7384dd2a801e3efd3d64e19fef419882b2a343a91408ce680755bfaf79bc
+  data.tar.gz: 3ee4d83c374287526c0f96a821c72d0254b2c1eed9d1cedef619c3bfd2425a2f21065b1571a7f065afebb6efe8c9c71ddf07f5e76678c755f5f5b99a3bfd4e06

data/CHANGELOG.md

@@ -1,18 +1,65 @@
 # Changelog
 
-## 2.0.0
+## [2.0.1]
+
+* Fixed `search` field type support [#330](https://github.com/bogdan/datagrid/issues/330)
+
+``` ruby
+class UsersGrid < Datagrid::Base
+  scope  { User }
+
+  filter(
+    :query, :string, input_options: { type: "search" }
+  ) do |value, scope|
+    scope.magic_search(value)
+  end
+end
+```
+
+Renders filter as:
+
+``` html
+<input type="search" name="users_grid[query]" id="users_grid_query"/>
+```
+
+* Added support for `default_filter_options` and added lambda support for `default_column_options` [#333](https://github.com/bogdan/datagrid/issues/333) by @tmikoss.
+
+``` ruby
+class UsersGrid < Datagrid::Base
+  scope { User }
+
+  self.default_column_options = -> (column) {
+    {header: I18n.t("datagrid.keywords.#{column.name}")}
+  }
+
+  self.default_filter_options = -> (filter) {
+    {
+      header: I18n.t("datagrid.keywords.user.#{filter.name}"),
+      input_options: filter.type == :string ? {type: "textarea"} : {},
+    }
+  }
+  
+  filter(:first_name, :string)
+  filter(:last_name, :string)
+
+  column(:first_name)
+  column(:last_name)
+end
+```
+
+## [2.0.0]
 
 Version 2 is a major update implementing a lot of major improvements
 at the cost of backward compatibility.
 
 [Changes and migration guide](./version-2)
 
-## 1.8.3
+## [1.8.3]
 
 * Fix rails hooking for version 7.1. [#327](https://github.com/bogdan/datagrid/issues/327)
 * Fix formatting of value for `date` and `datetime-local` input types
 
-## 1.8.2
+## [1.8.2]
 
 * Treat true/false as YES/NO when assigned as strings for xboolean filter.
 * Support infinite ranges for date, datetime and integer filters.
@@ -20,11 +67,11 @@ at the cost of backward compatibility.
 * Add `Datagrid#reset` method to reset a column cache.
 * Drop support of Rails 6.0 [#326](https://github.com/bogdan/datagrid/pull/326)
 
-## 1.8.1
+## [1.8.1]
 
 * Prioritize `input_options` over generated by default. [#319](https://github.com/bogdan/datagrid/pull/319)
 
-## 1.8.0
+## [1.8.0]
 
 * Support `input_options: {type: "textarea"}` as `<textarea/>` tag
 * Remove deprecated `eboolean` filter
@@ -37,18 +84,18 @@ at the cost of backward compatibility.
 * Add ability to specify `columns` option for `datagrid_row`.
   [#314](https://github.com/bogdan/datagrid/pull/314)
 
-## 1.7.0
+## [1.7.0]
 
 * Depend on `railties` instead of `rails` to prevent loading of unnecessary frameworks
 * Bugfix `File.exist?` usage for Ruby 3.0 [#307](https://github.com/bogdan/datagrid/issues/307)
 * Drop support of old Ruby versions (< 2.7) [#305](https://github.com/bogdan/datagrid/pull/305)
 * Drop support of old Rails versions (< 6.0) [#305](https://github.com/bogdan/datagrid/pull/305)
 
-## 1.6.3
+## [1.6.3]
 
 * Fix usage of options spread operator for Ruby 3.0 [#296](https://github.com/bogdan/datagrid/issues/296)
 
-## 1.6.2
+## [1.6.2]
 
 * Add `input_options` and `label_options` to `filter` method [#294](https://github.com/bogdan/datagrid/issues/294)
 * Fix `<option>` tag rendering for Rails 6.0

data/README.md

@@ -196,7 +196,7 @@ rails g datagrid::views
 
 All advanced frontend things are described in:
 
-[Frontend section on wiki](https://rubydoc.info/gems/datagrid/Datagrid/Helper)
+[Frontend documentation](https://rubydoc.info/gems/datagrid/Datagrid/Helper)
 
 ## Questions & Issues
 

data/lib/datagrid/columns/column.rb

@@ -8,37 +8,52 @@ module Datagrid
       class ResponseFormat
         attr_accessor :data_block, :html_block
 
+        # @!visibility private
         def initialize
           yield(self)
         end
 
+        # @!visibility private
         def data(&block)
           self.data_block = block
         end
 
+        # @!visibility private
         def html(&block)
           self.html_block = block
         end
 
+        # @!visibility private
         def call_data
           data_block.call
         end
 
+        # @!visibility private
         def to_s
           call_data.to_s
         end
 
+        # @!visibility private
         def call_html(context)
           context.instance_eval(&html_block)
         end
       end
 
-      attr_accessor :grid_class, :options, :data_block, :name, :html_block, :query
+      # @attribute [r] grid_class
+      #   @return [Class] grid class where column is defined
+      # @attribute [r] name
+      #   @return [Symbol] column name
+      # @attribute [r] options
+      #   @return [Hash<Symbol, Object>] column options
+      attr_reader :grid_class, :name, :query, :options, :data_block, :html_block
 
+      # @!visibility private
       def initialize(grid_class, name, query, options = {}, &block)
-        self.grid_class = grid_class
-        self.name = name.to_sym
-        self.options = options
+        @grid_class = grid_class
+        @name = name.to_sym
+        @query = query
+        @options = Datagrid::Utils.callable(grid_class.default_column_options, self).merge(options)
+
         if options[:class]
           Datagrid::Utils.warn_once(
             "column[class] option is deprecated. Use {tag_options: {class: ...}} instead.",
@@ -49,24 +64,26 @@ module Datagrid
           }
         end
         if options[:html] == true
-          self.html_block = block
+          @html_block = block
         else
-          self.data_block = block
+          @data_block = block
 
-          self.html_block = options[:html] if options[:html].is_a? Proc
+          @html_block = options[:html] if options[:html].is_a? Proc
         end
-        self.query = query
       end
 
+      # @deprecated Use {Datagrid::Columns#data_value} instead
       def data_value(model, grid)
         # backward compatibility method
         grid.data_value(name, model)
       end
 
+      # @deprecated Use {#header} instead
       def label
         options[:label]
       end
 
+      # @return [String] column header
       def header
         if (header = options[:header])
           Datagrid::Utils.callable(header)
@@ -75,7 +92,9 @@ module Datagrid
         end
       end
 
+      # @return [Object] column order expression
       def order
+        return nil if options[:order] == false
         if options.key?(:order) && options[:order] != true
           options[:order]
         else
@@ -83,10 +102,12 @@ module Datagrid
         end
       end
 
+      # @return [Boolean] weather column support order
       def supports_order?
-        order || order_by_value?
+        !!order || order_by_value?
       end
 
+      # @!visibility private
       def order_by_value(model, grid)
         if options[:order_by_value] == true
           grid.data_value(self, model)
@@ -95,6 +116,7 @@ module Datagrid
         end
       end
 
+      # @return [Boolean] weather a column should be ordered by value
       def order_by_value?
         !!options[:order_by_value]
       end
@@ -105,22 +127,27 @@ module Datagrid
         options[:order_desc]
       end
 
+      # @return [Boolean] weather a column should be displayed in HTML
       def html?
         options[:html] != false
       end
 
+      # @return [Boolean] weather a column should be displayed in data
       def data?
         data_block != nil
       end
 
+      # @return [Boolean] weather a column is explicitly marked mandatory
       def mandatory?
         !!options[:mandatory]
       end
 
+      # @return [Hash<Symbol, Object>] `tag_options` option value
       def tag_options
         options[:tag_options] || {}
       end
 
+      # @deprecated Use {#tag_options} instead.
       def html_class
         Datagrid::Utils.warn_once(
           "Column#html_class is deprecated. Use Column#tag_options instead.",
@@ -128,30 +155,38 @@ module Datagrid
         options[:class]
       end
 
+      # @return [Boolean] weather a `mandatory` option is explicitly set
       def mandatory_explicitly_set?
         options.key?(:mandatory)
       end
 
+      # @param [Datagrid::Base] grid object
+      # @return [Boolean] weather a column is available via `if` and `unless` options
       def enabled?(grid)
         ::Datagrid::Utils.process_availability(grid, options[:if], options[:unless])
       end
 
+      # @return [String] column console inspection
       def inspect
         "#<#{self.class} #{grid_class}##{name} #{options.inspect}>"
       end
 
+      # @return [String] column header
       def to_s
         header
       end
 
+      # @!visibility private
       def html_value(context, asset, grid)
         grid.html_value(name, context, asset)
       end
 
+      # @!visibility private
       def generic_value(model, grid)
         grid.generic_value(self, model)
       end
 
+      # @!visibility private
       def append_preload(relation)
         return relation unless preload
 
@@ -168,6 +203,7 @@ module Datagrid
         end
       end
 
+      # @return [Object] `preload` option value
       def preload
         preload = options[:preload]
 
@@ -178,6 +214,8 @@ module Datagrid
         end
       end
 
+      protected
+
       def driver
         grid_class.driver
       end

data/lib/datagrid/columns.rb

@@ -155,6 +155,10 @@ module Datagrid
   #
   #     self.default_column_options = { order: false }
   #
+  # It can also accept a proc with the column instance as an argument:
+  #
+  #     self.default_column_options = ->(column) { { order: column.name == :id } }
+  #
   # ## Columns Visibility
   #
   # Columns can be dynamically shown or hidden based on the grid's `column_names` accessor.
@@ -201,15 +205,19 @@ module Datagrid
   #     end
   module Columns
     # @!method default_column_options=(value)
-    #   @param [Hash] value default options passed to {#column} method call
-    #   @return [Hash] default options passed to {#column} method call
+    #   @param [Hash,Proc] value default options passed to {#column} method call.
+    #     When a proc is passed, it will be called with the column instance as an argument,
+    #     and expected to produce the options hash.
+    #   @return [Hash,Proc] default options passed to {#column} method call, or a proc that returns them.
     #   @example Disable default order
     #     self.default_column_options = { order: false }
     #   @example Makes entire report HTML
     #     self.default_column_options = { html: true }
+    #   @example Set the default header for all columns
+    #     self.default_column_options = ->(column) { { header: I18n.t(column.name, scope: 'my_scope.columns') } }
 
     # @!method default_column_options
-    #   @return [Hash] default options passed to {#column} method call
+    #   @return [Hash,Proc] default options passed to {#column} method call, or a proc that returns them.
     #   @see #default_column_options=
 
     # @!method batch_size=(value)
@@ -368,9 +376,10 @@ module Datagrid
         block ||= lambda do |model|
           model.public_send(name)
         end
+
         position = Datagrid::Utils.extract_position_from_options(columns, options)
         column = Datagrid::Columns::Column.new(
-          self, name, query, default_column_options.merge(options), &block
+          self, name, query, options, &block
         )
         columns.insert(position, column)
         column

data/lib/datagrid/core.rb

@@ -18,8 +18,7 @@ module Datagrid
   # Both having appropriate use cases
   #
   # @example Defining a scope in a grid class
-  #   class ProjectsGrid
-  #     include Datagrid
+  #   class ProjectsGrid < ApplicationGrid
   #     scope { Project.includes(:category) }
   #   end
   #
@@ -53,6 +52,7 @@ module Datagrid
         class_attribute :datagrid_attributes, instance_writer: false, default: []
         class_attribute :dynamic_block, instance_writer: false
         class_attribute :forbidden_attributes_protection, instance_writer: false, default: false
+        class_attribute :default_filter_options, default: {}
       end
     end
 

data/lib/datagrid/filters/base_filter.rb

@@ -15,7 +15,7 @@ module Datagrid
       def initialize(grid_class, name, **options, &block)
         self.grid_class = grid_class
         self.name = name.to_sym
-        self.options = options
+        self.options = Datagrid::Utils.callable(grid_class.default_filter_options, self).merge(options)
         self.block = block
       end
 

data/lib/datagrid/filters.rb

@@ -24,10 +24,10 @@ module Datagrid
   #     grid = UserGrid.new(posts_count: 1, name: "John")
   #     grid.assets # SELECT * FROM users WHERE users.posts_count > 1 AND name = 'John'
   #
-  # # Filter Block
-  #
   # Filter blocks should always return a chainable ORM object (e.g., `ActiveRecord::Relation`) rather than an `Array`.
   #
+  # # Filter Block
+  #
   # Filter blocks should have at least one argument representing the value assigned to the grid object attribute:
   #
   #     filter(:name, :string) # { |value| where(name: value) }
@@ -123,6 +123,16 @@ module Datagrid
   #     filter(:id, :integer, header: "Identifier")
   #     filter(:created_at, :date, range: true, default: proc { 1.month.ago.to_date..Date.today })
   #
+  # ## Default Filter Options
+  #
+  # Default options for all filters in a grid can be set using `default_filter_options`.
+  #
+  #     self.default_filter_options = { header: "" }
+  #
+  # It can also accept a proc with the filter instance as an argument:
+  #
+  #     self.default_filter_options = ->(filter) { { header: I18n.t(filter.name, scope: 'filters') } }
+  #
   # # Localization
   #
   # Filter labels can be localized or specified via the `:header` option:
@@ -130,6 +140,18 @@ module Datagrid
   #     filter(:created_at, :date, header: "Creation date")
   #     filter(:created_at, :date, header: proc { I18n.t("creation_date") })
   module Filters
+    # @!method default_filter_options=(value)
+    #   @param [Hash,Proc] value default options passed to {#filter} method call.
+    #     When a proc is passed, it will be called with the filter instance as an argument,
+    #     and expected to produce the options hash.
+    #   @return [Hash,Proc] default options passed to {#filter} method call, or a proc that returns them.
+    #   @example Set the default header for all filters
+    #     self.default_filter_options = ->(filter) { { header: I18n.t(filter.name, scope: 'my_scope.filters') } }
+
+    # @!method default_filter_options
+    #   @return [Hash,Proc] default options passed to {#filter} method call, or a proc that returns them.
+    #   @see #default_filter_options=
+
     require "datagrid/filters/base_filter"
     require "datagrid/filters/enum_filter"
     require "datagrid/filters/extended_boolean_filter"
@@ -163,6 +185,7 @@ module Datagrid
 
     included do
       include Datagrid::Core
+      class_attribute :default_filter_options, instance_writer: false, default: {}
       class_attribute :filters_array, default: []
     end
 
@@ -189,9 +212,11 @@ module Datagrid
       # @param [Symbol] name filter name
       # @param [Symbol] type filter type that defines type case and GUI representation of a filter
       # @param [Hash] options hash of options
-      # @param [Proc] block proc to apply the filter
+      # @yield [value, scope, grid] Block to apply the filter.
+      # @yieldparam [Object] value The value assigned to the filter.
+      # @yieldparam [Object] scope The current ORM scope being filtered.
+      # @yieldparam [Datagrid::Base] grid The datagrid instance.
       # @return [Datagrid::Filters::BaseFilter] Filter definition object
-      # @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.
@@ -213,6 +238,7 @@ module Datagrid
       # @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.
+      # @see Datagrid::Filters
       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

data/lib/datagrid/form_builder.rb

@@ -5,6 +5,14 @@ require "datagrid/deprecated_object"
 
 module Datagrid
   module FormBuilder
+    # @!visibility private
+    TYPE_METHOD_MAP = {
+      search: :search_field,
+      textarea: :text_area,
+      hidden: :hidden_field,
+      number: :number_field,
+    }.with_indifferent_access
+
     # @param filter_or_attribute [Datagrid::Filters::BaseFilter, String, Symbol] filter object or filter name
     # @param options [Hash] options of rails form input helper
     # @return [String] a form input html for the corresponding filter name
@@ -56,16 +64,12 @@ module Datagrid
         datetime_local_field filter.name, **options, &block
       when :date
         date_field filter.name, **options, &block
-      when :textarea
-        text_area filter.name, value: object.filter_value_as_string(filter), **options, &block
       when :checkbox
         value = options.fetch(:value, 1).to_s
-        options = { checked: true, **options } if filter.enum_checkboxes? && enum_checkbox_checked?(filter, value)
+        if filter.enum_checkboxes? && enum_checkbox_checked?(filter, value) && !options.key?(:checked)
+          options[:checked] = true
+        end
         check_box filter.name, options, value
-      when :hidden
-        hidden_field filter.name, **options
-      when :number
-        number_field filter.name, **options
       when :select
         select(
           filter.name,
@@ -80,7 +84,13 @@ module Datagrid
           &block
         )
       else
-        text_field filter.name, value: object.filter_value_as_string(filter), **options, &block
+        public_send(
+          TYPE_METHOD_MAP[type] || :text_field,
+          filter.name,
+          value: object.filter_value_as_string(filter),
+          **options,
+          &block
+        )
       end
     end
 

data/lib/datagrid/helper.rb

@@ -171,7 +171,7 @@ module Datagrid
   #
   # To customize Datagrid views:
   #
-  #     rake datagrid:copy_partials
+  #     rails g datagrid:views
   #
   # This creates files in `app/views/datagrid/`, which you can modify to suit your needs:
   #

data/lib/datagrid/ordering.rb

@@ -33,6 +33,35 @@ module Datagrid
       end
     end
 
+    # @!method order=(value)
+    #   Specify a column to be used to order the grid
+    #   @param [Symbol, String] value column name
+    #   @return [void]
+    #   @example
+    #     class MyGrid < ApplicationGrid
+    #       scope { User }
+    #       column(:name)
+    #     end
+    #
+    #     grid = MyGrid.new
+    #     grid.order = :name
+    #     grid.descending = true
+    #     grid.assets # => SELECT * FROM users ORDER BY users.name DESC
+
+    # @!method order
+    #   @return [Symbol, nil] specified order column name
+    #   @see #order=
+
+    # @!method descending=(value)
+    #   Specify an order direction for an order column
+    #   @param [Boolean] value specify `true` for descending order` or `false` for ascending
+    #   @return [void]
+    #   @see #order=
+
+    # @!method descending?
+    #   @return [Boolean] specified order direction
+    #   @see #descending=
+
     # @!visibility private
     def assets
       check_order_valid!

data/lib/datagrid/utils.rb

@@ -133,8 +133,8 @@ module Datagrid
           !property_availability(grid, unless_option, false)
       end
 
-      def callable(value)
-        value.respond_to?(:call) ? value.call : value
+      def callable(value, *arguments)
+        value.respond_to?(:call) ? value.call(*arguments) : value
       end
 
       protected

data/lib/datagrid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Datagrid
-  VERSION = "2.0.0"
+  VERSION = "2.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datagrid
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-20 00:00:00.000000000 Z
+date: 2025-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties