datagrid 1.8.2 → 2.0.0.pre.alpha

data/lib/datagrid/columns.rb

@@ -1,13 +1,208 @@
+# frozen_string_literal: true
+
 require "datagrid/utils"
 require "active_support/core_ext/class/attribute"
 
 module Datagrid
-
+  # Defines a column to be used for displaying data in a Datagrid.
+  #
+  #     class UserGrid < ApplicationGrid
+  #       scope do
+  #         User.order("users.created_at desc").joins(:group)
+  #       end
+  #
+  #       column(:name)
+  #       column(:group, order: "groups.name") do
+  #         self.group.name
+  #       end
+  #       column(:active, header: "Activated") do |user|
+  #         !user.disabled
+  #       end
+  #     end
+  #
+  # Each column is used to generate data for the grid.
+  #
+  # To create a grid displaying all users:
+  #
+  #     grid = UserGrid.new
+  #     grid.header    # => ["Group", "Name", "Disabled"]
+  #     grid.rows      # => [
+  #                    #      ["Steve", "Spammers", true],
+  #                    #      ["John", "Spoilers", true],
+  #                    #      ["Berry", "Good people", false]
+  #                    #    ]
+  #     grid.data      # => Header & Rows
+  #     grid.data_hash # => [
+  #                    #      { name: "Steve", group: "Spammers", active: true },
+  #                    #      { name: "John", group: "Spoilers", active: true },
+  #                    #      { name: "Berry", group: "Good people", active: false },
+  #                    #    ]
+  #     }
+  #
+  # ## Column Value
+  #
+  # The value of a column can be defined by passing a block to `Datagrid.column`.
+  #
+  # ### Basic Column Value
+  #
+  # If no block is provided, the column value is generated automatically by sending the column name method to the model.
+  #
+  #     column(:name) # => asset.name
+  #
+  # Using <tt>instance_eval</tt>:
+  #
+  #     column(:completed) { completed? }
+  #
+  # Using the asset as an argument:
+  #
+  #     column(:completed) { |asset| asset.completed? }
+  #
+  # ### Advanced Column Value
+  #
+  # You can also pass the Datagrid object itself to define more complex column values.
+  #
+  # Using filters with columns:
+  #
+  #     filter(:category) do |value|
+  #       where("category LIKE '%#{value}%'")
+  #     end
+  #
+  #     column(:exactly_matches_category) do |asset, grid|
+  #       asset.category == grid.category
+  #     end
+  #
+  # Combining columns:
+  #
+  #     column(:total_sales) do |merchant|
+  #       merchant.purchases.sum(:subtotal)
+  #     end
+  #     column(:number_of_sales) do |merchant|
+  #       merchant.purchases.count
+  #     end
+  #     column(:average_order_value) do |_, _, row|
+  #       row.total_sales / row.number_of_sales
+  #     end
+  #
+  # ## Using Database Expressions
+  #
+  # Columns can use database expressions to directly manipulate data in the database.
+  #
+  #     column(:count_of_users, 'count(user_id)')
+  #     column(:uppercase_name, 'upper(name)')
+  #
+  # ## HTML Columns
+  #
+  # Columns can have different formats for HTML and non-HTML representations.
+  #
+  #     column(:name) do |asset|
+  #       format(asset.name) do |value|
+  #         content_tag(:strong, value)
+  #       end
+  #     end
+  #
+  # ## Column Value Cache
+  #
+  # Enables grid-level caching for column values.
+  #
+  #     self.cached = true
+  #
+  # ## Ordering
+  #
+  # Columns can specify SQL ordering expressions using the `:order` and `:order_desc` options.
+  #
+  # Basic ordering:
+  #
+  #     column(:group_name, order: "groups.name") { self.group.name }
+  #
+  # In example above descending order is automatically inherited from ascending order specified.
+  # When such default is not enough, specify both options together:
+  #
+  #     column(
+  #       :priority,
+  #       # models with null priority are always on bottom
+  #       # no matter if sorting ascending or descending
+  #       order: "priority is not null desc, priority",
+  #       order_desc: "priority is not null desc, priority desc"
+  #     )
+  #
+  # Disable order like this:
+  #
+  #     column(:title, order: false)
+  #
+  # Order by joined table
+  # Allows to join specified table only when order is enabled
+  # for performance:
+  #
+  #     column(:profile_updated_at, order: proc { |scope|
+  #       scope.joins(:profile).order("profiles.updated_at")
+  #     }) do |model|
+  #       model.profile.updated_at.to_date
+  #     end
+  #
+  # Order by a calculated value
+  #
+  #     column(
+  #       :duration_request,
+  #       order: "(requests.finished_at - requests.accepted_at)"
+  #     ) do |model|
+  #       Time.at(model.finished_at - model.accepted_at).strftime("%H:%M:%S")
+  #     end
+  #
+  # ## Default Column Options
+  #
+  # Default options for all columns in a grid can be set using `default_column_options`.
+  #
+  #     self.default_column_options = { order: false }
+  #
+  # ## Columns Visibility
+  #
+  # Columns can be dynamically shown or hidden based on the grid's `column_names` accessor.
+  #
+  #     grid.column_names = [:id, :name]
+  #
+  # ## Dynamic Columns
+  #
+  # Columns can be defined dynamically on a grid instance or based on data.
+  #
+  # Adding a dynamic column:
+  #
+  #     grid.column(:extra_data) do |model|
+  #       model.extra_data
+  #     end
+  #
+  # ## Localization
+  #
+  # Column headers can be localized using the `:header` option or through i18n files.
+  #
+  #     column(:active, header: Proc.new { I18n.t("activated") })
+  #
+  # ## Preloading Associations
+  #
+  # Preload database associations for better performance.
+  #
+  # Automatic association preloading:
+  #
+  #     column(:group) do |user|
+  #       user.group.name
+  #     end
+  #
+  # Custom preloading:
+  #
+  #     column(:account_name, preload: { |s| s.includes(:account) })
+  #
+  # ## Decorator
+  #
+  # A decorator or presenter class can be used around each object in the `scope`.
+  #
+  #     decorate { UserPresenter }
+  #     column(:created_at) do |presenter|
+  #       presenter.user.created_at
+  #     end
   module Columns
     require "datagrid/columns/column"
 
-    # @!method default_column_options=
-    # @param value [Hash] default options passed to #column method call
+    # @!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
@@ -19,8 +214,8 @@ module Datagrid
     # @return [Hash]
     # @see #default_column_options=
 
-    # @!method batch_size=
-    # @param value [Integer] Specify a default batch size when generating CSV or just data. Default: 1000
+    # @!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
     #   self.batch_size = 500
@@ -33,8 +228,9 @@ module Datagrid
     # @see #batch_size=
 
     # @visibility private
+    # @param [Object] base
     def self.included(base)
-      base.extend         ClassMethods
+      base.extend ClassMethods
       base.class_eval do
         include Datagrid::Core
 
@@ -47,7 +243,6 @@ module Datagrid
     end
 
     module ClassMethods
-
       # @param data [Boolean] if true returns only columns with data representation. Default: false.
       # @param html [Boolean] if true returns only columns with html columns. Default: false.
       # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
@@ -62,7 +257,7 @@ module Datagrid
       #
       # @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 options [Hash{Symbol => Object}] hash of options
       # @param block [Block] proc to calculate a column value
       # @return [Datagrid::Columns::Column]
       #
@@ -71,7 +266,7 @@ module Datagrid
       # * <tt>html</tt> - determines if current column should be present in html table and how is it formatted
       # * <tt>order</tt> - determines if this column could be sortable and how.
       #   The value of order is explicitly passed to ORM ordering method.
-      #   Ex: <tt>"created_at, id"</tt> for ActiveRecord, <tt>[:created_at, :id]</tt> for Mongoid
+      #   Example: <tt>"created_at, id"</tt> for ActiveRecord, <tt>[:created_at, :id]</tt> for Mongoid
       # * <tt>order_desc</tt> - determines a descending order for given column
       #   (only in case when <tt>:order</tt> can not be easily reversed by ORM)
       # * <tt>order_by_value</tt> - used in case it is easier to perform ordering at ruby level not on database level.
@@ -85,6 +280,8 @@ module Datagrid
       # * <tt>if</tt> - the column is shown if the reult of calling this argument is true
       # * <tt>unless</tt> - the column is shown unless the reult of calling this argument is true
       # * <tt>preload</tt> - spefies which associations of the scope should be preloaded for this column
+      # * `tag_options` - specify HTML attributes to be set for `<td>` or `<th>` 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)
@@ -115,7 +312,7 @@ module Datagrid
       # @example
       #   column(:name) do |model|
       #     format(model.name) do |value|
-      #       content_tag(:strong, value)
+      #       tag.strong(value)
       #     end
       #   end
       def format(value, &block)
@@ -146,23 +343,25 @@ module Datagrid
         end
         return self.decorator = block unless model
         return model unless decorator
+
         presenter = ::Datagrid::Utils.apply_args(model, &decorator)
-        presenter = presenter.is_a?(Class) ?  presenter.new(model) : presenter
+        presenter = presenter.new(model) if presenter.is_a?(Class)
         block_given? ? yield(presenter) : presenter
       end
 
       # @!visibility private
       def inherited(child_class)
-        super(child_class)
-        child_class.columns_array = self.columns_array.clone
+        super
+        child_class.columns_array = columns_array.clone
       end
 
       # @!visibility private
       def filter_columns(columns_array, *names, data: false, html: false)
         names.compact!
-        if names.size >= 1 && names.all? {|n| n.is_a?(Datagrid::Columns::Column) && n.grid_class == self.class}
+        if names.size >= 1 && names.all? { |n| n.is_a?(Datagrid::Columns::Column) && n.grid_class == self.class }
           return names
         end
+
         names.map!(&:to_sym)
         columns_array.select do |column|
           (!data || column.data?) &&
@@ -186,21 +385,21 @@ module Datagrid
       end
 
       # @!visibility private
-      def find_column_by_name(columns,name)
+      def find_column_by_name(columns, name)
         return name if name.is_a?(Datagrid::Columns::Column)
+
         columns.find do |col|
           col.name.to_sym == name.to_sym
         end
       end
-
     end
 
     # @!visibility private
     def assets
       append_column_preload(
         driver.append_column_queries(
-          super, columns.select(&:query)
-        )
+          super, columns.select(&:query),
+        ),
       )
     end
 
@@ -223,7 +422,7 @@ module Datagrid
     # @return [Hash] A mapping where keys are column names and values are column values for the given asset
     def hash_for(asset)
       result = {}
-      self.data_columns.each do |column|
+      data_columns.each do |column|
         result[column.name] = data_value(column, asset)
       end
       result
@@ -233,18 +432,17 @@ module Datagrid
     # @return [Array<Array<Object>>] with data for each row in datagrid assets without header
     def rows(*column_names)
       map_with_batches do |asset|
-        self.row_for(asset, *column_names)
+        row_for(asset, *column_names)
       end
     end
 
     # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
     # @return [Array<Array<Object>>] data for each row in datagrid assets with header.
     def data(*column_names)
-      self.rows(*column_names).unshift(self.header(*column_names))
+      rows(*column_names).unshift(header(*column_names))
     end
 
-    # Return Array of Hashes where keys are column names and values are column values
-    # for each row in filtered datagrid relation.
+    # @return [Array<Hash{Symbol => Object}>] an array of hashes representing the rows in the filtered datagrid relation
     #
     # @example
     #   class MyGrid
@@ -274,9 +472,9 @@ module Datagrid
     def to_csv(*column_names, **options)
       require "csv"
       CSV.generate(
-        headers: self.header(*column_names),
+        headers: header(*column_names),
         write_headers: true,
-        **options
+        **options,
       ) do |csv|
         each_with_batches do |asset|
           csv << row_for(asset, *column_names)
@@ -284,8 +482,9 @@ module Datagrid
       end
     end
 
-
     # @param column_names [Array<Symbol, String>]
+    # @param [Boolean] data return only data columns
+    # @param [Boolean] html return only HTML columns
     # @return [Array<Datagrid::Columns::Column>] all columns selected in grid instance
     # @example
     #   MyGrid.new.columns # => all defined columns
@@ -294,22 +493,25 @@ module Datagrid
     #   grid.columns(:id, :category) # => id and category column
     def columns(*column_names, data: false, html: false)
       self.class.filter_columns(
-        columns_array, *column_names, data: data, html: html
+        columns_array, *column_names, data: data, html: html,
       ).select do |column|
         column.enabled?(self)
       end
     end
 
-    # @param column_names [Array<String, Symbol>] list of column names if you want to limit data only to specified columns
-    # @return columns that can be represented in plain data(non-html) way
-    def data_columns(*column_names, **options)
-      self.columns(*column_names, **options, data: true)
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns
+    # @param [Boolean] html return only HTML columns
+    # @return [Array<Datagrid::Columns::Column>] columns that can be represented in plain data(non-html) way
+    def data_columns(*column_names, html: false)
+      columns(*column_names, html: html, data: true)
     end
 
     # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
+    # @param [Boolean] data return only data columns
     # @return all columns that can be represented in HTML table
-    def html_columns(*column_names, **options)
-      self.columns(*column_names, **options, html: true)
+    def html_columns(*column_names, data: false)
+      columns(*column_names, data: data, html: true)
     end
 
     # Finds a column definition by name
@@ -324,7 +526,7 @@ module Datagrid
     # @example
     #   column(:name) do |model|
     #     format(model.name) do |value|
-    #       content_tag(:strong, value)
+    #       tag.strong(value)
     #     end
     #   end
     #
@@ -374,7 +576,8 @@ module Datagrid
       super
     end
 
-    # @return [Array<Datagrid::Columns::Column>] all columns that are possible to be displayed for the current grid object
+    # @return [Array<Datagrid::Columns::Column>] all columns
+    #   that are possible to be displayed for the current grid object
     #
     # @example
     #   class MyGrid
@@ -402,6 +605,7 @@ module Datagrid
       column = column_by_name(column_name)
       cache(column, asset, :data_value) do
         raise "no data value for #{column.name} column" unless column.data?
+
         result = generic_value(column, asset)
         result.is_a?(Datagrid::Columns::Column::ResponseFormat) ? result.call_data : result
       end
@@ -409,7 +613,7 @@ module Datagrid
 
     # @return [Object] a cell HTML value for given column name and asset and view context
     def html_value(column_name, context, asset)
-      column  = column_by_name(column_name)
+      column = column_by_name(column_name)
       cache(column, asset, :html_value) do
         if column.html? && column.html_block
           value_from_html_block(context, asset, column)
@@ -462,9 +666,8 @@ module Datagrid
         return yield
       end
       key = cache_key(asset)
-      unless key
-        raise(Datagrid::CacheKeyError, "Datagrid Cache key is #{key.inspect} for #{asset.inspect}.")
-      end
+      raise(Datagrid::CacheKeyError, "Datagrid Cache key is #{key.inspect} for #{asset.inspect}.") unless key
+
       @cache[column.name] ||= {}
       @cache[column.name][key] ||= {}
       @cache[column.name][key][type] ||= yield
@@ -477,10 +680,12 @@ module Datagrid
         driver.default_cache_key(asset)
       end
     rescue NotImplementedError
-      raise Datagrid::ConfigurationError, "#{self} is setup to use cache. But there was appropriate cache key found for #{asset.inspect}. Please set cached option to block with asset as argument and cache key as returning value to resolve the issue."
+      raise Datagrid::ConfigurationError,
+        <<~MSG
+          #{self} is setup to use cache. But there was appropriate cache key found for #{asset.inspect}.
+        MSG
     end
 
-
     def map_with_batches(&block)
       result = []
       each_with_batches do |asset|
@@ -490,7 +695,7 @@ module Datagrid
     end
 
     def each_with_batches(&block)
-      if batch_size && batch_size > 0
+      if batch_size&.positive?
         driver.batch_each(assets, batch_size, &block)
       else
         assets.each(&block)
@@ -500,7 +705,7 @@ module Datagrid
     def value_from_html_block(context, asset, column)
       args = []
       remaining_arity = column.html_block.arity
-      remaining_arity = 1 if remaining_arity < 0
+      remaining_arity = 1 if remaining_arity.negative?
 
       asset = decorate(asset)
 
@@ -509,7 +714,7 @@ module Datagrid
         remaining_arity -= 1
       end
 
-      args << asset if remaining_arity > 0
+      args << asset if remaining_arity.positive?
       args << self if remaining_arity > 1
 
       context.instance_exec(*args, &column.html_block)
@@ -523,9 +728,13 @@ module Datagrid
         @model = model
       end
 
-      def method_missing(meth, *args, &blk)
+      def method_missing(meth, *_args)
         @grid.data_value(meth, @model)
       end
+
+      def respond_to_missing?(meth, include_private = false)
+        !!@grid.column_by_name(meth) || super
+      end
     end
   end
 end

data/lib/datagrid/configuration.rb

@@ -1,14 +1,27 @@
-module Datagrid
-
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
+# frozen_string_literal: true
 
-  def self.configure
-    yield(configuration)
-  end
-
-  # Datagrid configuration object
+module Datagrid
+  # ## Configuration
+  #
+  # Datagrid provides several configuration options.
+  #
+  # Here is the API reference and a description of the available options:
+  #
+  # ``` ruby
+  # 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).
+  #   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).
+  #   config.datetime_formats = ["%m/%d/%Y %h:%M", "%Y-%m-%d %h:%M:%s"]
+  # end
+  # ```
+  #
+  # These options can be set globally in your application to customize Datagrid’s behavior.
   class Configuration
     # @return [Array<String>] Date parsing formats
     attr_accessor :date_formats