datagrid 1.6.3 → 1.8.0

data/lib/datagrid/filters.rb

@@ -5,7 +5,6 @@ module Datagrid
 
     require "datagrid/filters/base_filter"
     require "datagrid/filters/enum_filter"
-    require "datagrid/filters/boolean_enum_filter"
     require "datagrid/filters/extended_boolean_filter"
     require "datagrid/filters/boolean_filter"
     require "datagrid/filters/date_filter"
@@ -18,24 +17,23 @@ module Datagrid
     require "datagrid/filters/dynamic_filter"
 
     FILTER_TYPES = {
-      :date => Filters::DateFilter,
-      :datetime => Filters::DateTimeFilter,
-      :string => Filters::StringFilter,
-      :default => Filters::DefaultFilter,
-      :eboolean => Filters::BooleanEnumFilter ,
-      :xboolean => Filters::ExtendedBooleanFilter ,
-      :boolean => Filters::BooleanFilter ,
-      :integer => Filters::IntegerFilter,
-      :enum => Filters::EnumFilter,
-      :float => Filters::FloatFilter,
-      :dynamic => Filters::DynamicFilter
+      date: Filters::DateFilter,
+      datetime: Filters::DateTimeFilter,
+      string: Filters::StringFilter,
+      default: Filters::DefaultFilter,
+      xboolean: Filters::ExtendedBooleanFilter ,
+      boolean: Filters::BooleanFilter ,
+      integer: Filters::IntegerFilter,
+      enum: Filters::EnumFilter,
+      float: Filters::FloatFilter,
+      dynamic: Filters::DynamicFilter
     }
 
-    class DefaultFilterScope
-    end
+    DEFAULT_FILTER_BLOCK = Object.new
 
-    def self.included(base) #:nodoc:
-      base.extend         ClassMethods
+    # @!visibility private
+    def self.included(base)
+      base.extend ClassMethods
       base.class_eval do
 
         include Datagrid::Core
@@ -44,14 +42,19 @@ module Datagrid
         self.filters_array = []
 
       end
-      base.send :include, InstanceMethods
-    end # self.included
+      base.include InstanceMethods
+    end
 
     module ClassMethods
 
       # Returns filter definition object by name
       def filter_by_name(attribute)
-        return attribute if attribute.is_a?(Datagrid::Filters::BaseFilter)
+        if attribute.is_a?(Datagrid::Filters::BaseFilter)
+          unless ancestors.include?(attribute.grid_class)
+            raise "#{attribute.grid_class}##{attribute.name} filter doen't belong to #{self.class}"
+          end
+          return attribute
+        end
         self.filters.find do |filter|
           filter.name == attribute.to_sym
         end
@@ -90,7 +93,8 @@ module Datagrid
       #   Accepts a block or a symbol with an instance method name
       # * <tt>:unless</tt> - specify the reverse condition when the filter can be dislayed and used.
       #   Accepts a block or a symbol with an instance method name
-      # * <tt>:input_options</tt> - options passed when rendering html input tag attributes
+      # * <tt>:input_options</tt> - options passed when rendering html input tag attributes.
+      #   Use <tt>input_options.type</tt> to control input type including <tt>textarea</tt>.
       # * <tt>:label_options</tt> - options passed when rendering html label tag attributes
       #
       # See: https://github.com/bogdan/datagrid/wiki/Filters for examples
@@ -108,7 +112,7 @@ module Datagrid
       end
 
       def default_filter
-        DefaultFilterScope.new
+        DEFAULT_FILTER_BLOCK
       end
 
       def inspect
@@ -132,11 +136,12 @@ module Datagrid
           "#{filter.name}: #{filter.type}"
         end.join(", ")
       end
-    end # ClassMethods
+    end
 
     module InstanceMethods
 
-      def initialize(*args, &block) # :nodoc:
+      # @!visibility private
+      def initialize(*args, &block)
         self.filters_array = self.class.filters_array.clone
         self.filters_array.each do |filter|
           self[filter.name] = filter.default(self)
@@ -144,7 +149,8 @@ module Datagrid
         super(*args, &block)
       end
 
-      def assets # :nodoc:
+      # @!visibility private
+      def assets
         apply_filters(super, filters)
       end
 
@@ -178,11 +184,18 @@ module Datagrid
       # Returns select options for specific filter or filter name
       # If given filter doesn't support select options raises `ArgumentError`
       def select_options(filter)
-        filter = filter_by_name(filter)
-        unless filter.class.included_modules.include?(::Datagrid::Filters::SelectOptions)
-          raise ::Datagrid::ArgumentError, "#{filter.name} with type #{FILTER_TYPES.invert[filter.class].inspect} can not have select options"
-        end
-        filter.select(self)
+        find_select_filter(filter).select(self)
+      end
+
+      # Sets all options as selected for a filter that has options
+      def select_all(filter)
+        filter = find_select_filter(filter)
+        self[filter.name] = select_values(filter)
+      end
+
+      # Returns all values that can be set to a filter with select options
+      def select_values(filter)
+        find_select_filter(filter).select_values(self)
       end
 
       def default_filter
@@ -198,12 +211,21 @@ module Datagrid
 
       protected
 
+      def find_select_filter(filter)
+        filter = filter_by_name(filter)
+        unless filter.class.included_modules.include?(::Datagrid::Filters::SelectOptions)
+          raise ::Datagrid::ArgumentError,
+            "#{self.class.name}##{filter.name} with type #{FILTER_TYPES.invert[filter.class].inspect} can not have select options"
+        end
+        filter
+      end
+
       def apply_filters(current_scope, filters)
         filters.inject(current_scope) do |result, filter|
           filter.apply(self, result, filter_value(filter))
         end
       end
-    end # InstanceMethods
+    end
 
   end
 end

data/lib/datagrid/form_builder.rb

@@ -2,30 +2,42 @@ require "action_view"
 
 module Datagrid
   module FormBuilder
-
-    # Returns a form input html for the corresponding filter name
-    def datagrid_filter(filter_or_attribute, options = {}, &block)
+    # @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
+    #   * <tt>select</tt> for enum, xboolean filter types
+    #   * <tt>check_box</tt> for boolean filter type
+    #   * <tt>text_field</tt> for other filter types
+    def datagrid_filter(filter_or_attribute, partials: nil, **options, &block)
       filter = datagrid_get_filter(filter_or_attribute)
-      options = {
+      self.send(
+        filter.form_builder_helper_name, filter,
         **filter.input_options,
         **add_html_classes(options, filter.name, datagrid_filter_html_class(filter)),
-      }
-      # Prevent partials option from appearing in HTML attributes
-      options.delete(:partials) # Legacy option
-      self.send(filter.form_builder_helper_name, filter, options, &block)
+        &block
+      )
     end
 
-    # Returns a form label html for the corresponding filter name
+    # @param filter_or_attribute [Datagrid::Filters::BaseFilter, String, Symbol] filter object or filter name
+    # @param text [String, nil] label text, defaults to <tt>filter.header</tt>
+    # @param options [Hash] options of rails <tt>label</tt> helper
+    # @return [String] a form label html for the corresponding filter name
     def datagrid_label(filter_or_attribute, text = nil, **options, &block)
       filter = datagrid_get_filter(filter_or_attribute)
       label(filter.name, text || filter.header, **filter.label_options, **options, &block)
     end
 
-    protected
-    def datagrid_boolean_enum_filter(attribute_or_filter, options = {})
-      datagrid_enum_filter(attribute_or_filter, options)
+    def datagrid_filter_input(attribute_or_filter, **options)
+      filter = datagrid_get_filter(attribute_or_filter)
+      value = object.filter_value_as_string(filter)
+      if options[:type]&.to_sym == :textarea
+        text_area filter.name, value: value, **options, type: nil
+      else
+        text_field filter.name, value: value, **options
+      end
     end
 
+    protected
     def datagrid_extended_boolean_filter(attribute_or_filter, options = {})
       datagrid_enum_filter(attribute_or_filter, options)
     end
@@ -43,27 +55,25 @@ module Datagrid
     end
 
     def datagrid_default_filter(attribute_or_filter, options = {})
-      filter = datagrid_get_filter(attribute_or_filter)
-      text_field filter.name, value: object.filter_value_as_string(filter), **options
+      datagrid_filter_input(attribute_or_filter, **options)
     end
 
     def datagrid_enum_filter(attribute_or_filter, options = {}, &block)
       filter = datagrid_get_filter(attribute_or_filter)
       if filter.checkboxes?
-        partial = partial_path('enum_checkboxes')
         options = add_html_classes(options, 'checkboxes')
         elements = object.select_options(filter).map do |element|
           text, value = @template.send(:option_text_and_value, element)
           checked = enum_checkbox_checked?(filter, value)
           [value, text, checked]
         end
-        @template.render(
-          :partial => partial,
-          :locals => {
-            :elements => elements,
-            :form => self,
-            :filter => filter,
-            :options => options,
+        render_partial(
+          'enum_checkboxes',
+          {
+            elements: elements,
+            form: self,
+            filter: filter,
+            options: options,
           }
         )
       else
@@ -105,21 +115,26 @@ module Datagrid
       filter = datagrid_get_filter(attribute_or_filter)
       input_name = "#{object_name}[#{filter.name.to_s}][]"
       field, operation, value = object.filter_value(filter)
-      options = options.merge(:name => input_name)
+      options = options.merge(name: input_name)
       field_input = dynamic_filter_select(
         filter.name,
         object.select_options(filter) || [],
         {
-          :include_blank => filter.include_blank,
-          :prompt => filter.prompt,
-          :include_hidden => false,
-          :selected => field
+          include_blank: filter.include_blank,
+          prompt: filter.prompt,
+          include_hidden: false,
+          selected: field
         },
         add_html_classes(options, "field")
       )
       operation_input = dynamic_filter_select(
         filter.name, filter.operations_select,
-        {:include_blank => false, :include_hidden => false, :prompt => false, :selected => operation },
+        {
+          include_blank: false,
+          include_hidden: false,
+          prompt: false,
+          selected: operation,
+        },
         add_html_classes(options, "operation")
       )
       value_input = text_field(filter.name, **add_html_classes(options, "value"), value: value)
@@ -141,20 +156,19 @@ module Datagrid
     def datagrid_range_filter(type, attribute_or_filter, options = {})
       filter = datagrid_get_filter(attribute_or_filter)
       if filter.range?
-        partial = partial_path('range_filter')
-        options = options.merge(:multiple => true)
+        options = options.merge(multiple: true)
         from_options = datagrid_range_filter_options(object, filter, :from, options)
         to_options = datagrid_range_filter_options(object, filter, :to, options)
-        @template.render :partial => partial, :locals => {
-          :from_options => from_options, :to_options => to_options, :filter => filter, :form => self
+        render_partial 'range_filter', {
+          from_options: from_options, to_options: to_options, filter: filter, form: self
         }
       else
-        datagrid_default_filter(filter, options)
+        datagrid_filter_input(filter, **options)
       end
     end
 
     def datagrid_range_filter_options(object, filter, type, options)
-      type_method_map = {:from => :first, :to => :last}
+      type_method_map = {from: :first, to: :last}
       options = add_html_classes(options, type)
       options[:value] = filter.format(object[filter.name].try(type_method_map[type]))
       # In case of datagrid ranged filter
@@ -172,7 +186,7 @@ module Datagrid
     end
 
     def datagrid_string_filter(attribute_or_filter, options = {})
-      datagrid_default_filter(attribute_or_filter, options)
+      datagrid_range_filter(:string, attribute_or_filter, options)
     end
 
     def datagrid_float_filter(attribute_or_filter, options = {})
@@ -211,6 +225,10 @@ module Datagrid
       File.join('datagrid', name)
     end
 
+    def render_partial(name, locals)
+      @template.render partial: partial_path(name), locals: locals
+    end
+
     class Error < StandardError
     end
   end

data/lib/datagrid/helper.rb

@@ -4,30 +4,28 @@ require "action_view"
 module Datagrid
   module Helper
 
-    # Returns individual cell value from the given grid, column name and model
-    # Allows to render custom HTML layout for grid data
-    #
+    # @param grid [Datagrid] grid object
+    # @param column [Datagrid::Columns::Column, String, Symbol] column name
+    # @param model [Object] an object from grid scope
+    # @return [Object] individual cell value from the given grid, column name and model
+    # @example
     #   <ul>
     #     <% @grid.columns.each do |column|
     #       <li><%= column.header %>: <%= datagrid_value(@grid, column.name, @resource %></li>
     #     <% end %>
     #   </ul>
-    #
-    def datagrid_value(grid, column_name, model)
-      datagrid_renderer.format_value(grid, column_name, model)
+    def datagrid_value(grid, column, model)
+      datagrid_renderer.format_value(grid, column, model)
     end
 
-    def datagrid_format_value(grid, column_name, model) #:nodoc:
-      datagrid_value(grid, column_name, model)
+    # @!visibility private
+    def datagrid_format_value(grid, column, model)
+      datagrid_value(grid, column, model)
     end
 
     # 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:
-    #
-    #   assets = grid.assets.page(params[:page])
-    #   datagrid_table(grid, assets, options)
-    #
     # Supported options:
     #
     # * <tt>:html</tt> - hash of attributes for <table> tag
@@ -38,6 +36,12 @@ module Datagrid
     #   and needs different columns. Default: all defined columns.
     # * <tt>:partials</tt> - Path for partials lookup.
     #   Default: 'datagrid'.
+    # @param grid [Datagrid] grid object
+    # @param assets [Array] objects from grid scope
+    # @return [String] table tag HTML markup
+    # @example
+    #   assets = grid.assets.page(params[:page])
+    #   datagrid_table(grid, assets, options)
     def datagrid_table(grid, assets = grid.assets, **options)
       datagrid_renderer.table(grid, assets, **options)
     end
@@ -48,8 +52,13 @@ module Datagrid
     #
     # * <tt>:order</tt> - display ordering controls built-in into header
     #   Default: true
+    # * <tt>:columns</tt> - 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.
     # * <tt>:partials</tt> - Path for partials lookup.
     #   Default: 'datagrid'.
+    # @param grid [Datagrid] grid object
+    # @return [String] HTML table header tag markup
     def datagrid_header(grid, options = {})
       datagrid_renderer.header(grid, options)
     end
@@ -66,6 +75,7 @@ module Datagrid
     # * <tt>:partials</tt> - Path for partials lookup.
     #   Default: 'datagrid'.
     #
+    # @example
     #   = datagrid_rows(grid) # Generic table rows Layout
     #
     #   = datagrid_rows(grid) do |row| # Custom Layout
@@ -93,73 +103,45 @@ module Datagrid
     # * <tt>:partials</tt> - Path for form partial lookup.
     #   Default: 'datagrid'.
     # * All options supported by Rails <tt>form_for</tt> helper
+    # @param grid [Datagrid] grid object
+    # @return [String] form HTML tag markup
     def datagrid_form_for(grid, options = {})
       datagrid_renderer.form_for(grid, options)
     end
 
     # Provides access to datagrid columns data.
-    #
-    #   # Suppose that <tt>grid</tt> has first_name and last_name columns
+    # Used in case you want to build html table completelly manually
+    # @param grid [Datagrid] grid object
+    # @param asset [Object] object from grid scope
+    # @param block [Proc] block with Datagrid::Helper::HtmlRow as an argument returning a HTML markup as a String
+    # @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
     #   <%= datagrid_row(grid, user) do |row| %>
     #     <tr>
     #       <td><%= row.first_name %></td>
     #       <td><%= row.last_name %></td>
     #     </tr>
     #   <% end %>
-    #
-    # Used in case you want to build html table completelly manually
-    def datagrid_row(grid, asset, &block)
-      HtmlRow.new(self, grid, asset).tap do |row|
-        if block_given?
-          return capture(row, &block)
-        end
-      end
+    # @example
+    #   <% 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
 
     # Generates an ascending or descending order url for the given column
+    # @param grid [Datagrid] grid object
+    # @param column [Datagrid::Columns::Column, String, Symbol] column name
+    # @param descending [Boolean] specifies order direction. Ascending if false, otherwise descending.
+    # @return [String] order layout HTML markup
     def datagrid_order_path(grid, column, descending)
       datagrid_renderer.order_path(grid, column, descending, request)
     end
 
-    # Represents a datagrid row that provides access to column values for the given asset
-    #
-    #   row = datagrid_row(grid, user)
-    #   row.first_name # => "<strong>Bogdan</strong>"
-    #   row.grid       # => Grid object
-    #   row.asset      # => User object
-    class HtmlRow
-
-      include Enumerable
-
-      attr_reader :grid, :asset
-
-      def initialize(context, grid, asset) # :nodoc:
-        @context = context
-        @grid = grid
-        @asset = asset
-      end
-
-      # Return a column value for given column name
-      def get(column)
-        @context.datagrid_value(@grid, column, @asset)
-      end
-
-      # Iterates over all column values that are available in the row
-      def each
-        @grid.columns.each do |column|
-          yield(get(column))
-        end
-      end
-
-      protected
-      def method_missing(method, *args, &blk)
-        if column = @grid.column_by_name(method)
-          get(column)
-        else
-          super
-        end
-      end
-    end
 
     protected
 

data/lib/datagrid/locale/en.yml

@@ -2,22 +2,26 @@ en:
   datagrid:
     no_results:
       "――"
+
     table:
       order:
         asc: "↑"
         desc: "↓"
       no_columns: "No columns selected"
+
     form:
       search: "Search"
       reset: "Reset"
+
     filters:
       xboolean:
         "yes": "Yes"
         "no": "No"
-
       dynamic:
         operations:
           ">=": "≥"
           "<=": "≤"
           "=": "="
           "=~": "≈"
+      range:
+        separator: " - "

data/lib/datagrid/ordering.rb

@@ -1,10 +1,12 @@
 require "datagrid/columns"
 
 module Datagrid
+  # Raised when grid order value is incorrect
   class OrderUnsupported < StandardError
   end
   module Ordering
 
+    # @!visibility private
     def self.included(base)
       base.extend         ClassMethods
       base.class_eval do
@@ -25,39 +27,38 @@ module Datagrid
         alias descending? descending
 
       end
-      base.send :include, InstanceMethods
-    end # self.included
+      base.include InstanceMethods
+    end
 
+    # @!visibility private
     module ClassMethods
-
       def order_unsupported(name, reason)
         raise Datagrid::OrderUnsupported, "Can not sort #{self.inspect} by ##{name}: #{reason}"
       end
-
-    end # ClassMethods
+    end
 
     module InstanceMethods
 
-      def assets # :nodoc:
+      # @!visibility private
+      def assets
         check_order_valid!
         apply_order(super)
       end
 
-      # Returns a column definition that is currently used to order assets
-      #
+      # @return [Datagrid::Columns::Column, nil] a column definition that is currently used to order assets
+      # @example
       #   class MyGrid
       #     scope { Model }
       #     column(:id)
       #     column(:name)
       #   end
-      #   MyGrid.new(:order => "name").order_column # => #<Column name: "name", ...>
-      #
+      #   MyGrid.new(order: "name").order_column # => #<Column name: "name", ...>
       def order_column
-        order && column_by_name(order)
+        order ? column_by_name(order) : nil
       end
 
-      # Returns true if given grid is ordered by given column.
-      # <tt>column</tt> can be given as name or as column object
+      # @param column [String, Datagrid::Columns::Column]
+      # @return [Boolean] true if given grid is ordered by given column.
       def ordered_by?(column)
         order_column == column_by_name(column)
       end
@@ -127,7 +128,6 @@ module Datagrid
           self.class.order_unsupported(order_column.name, "Order option proc can not handle more than one argument")
         end
       end
-    end # InstanceMethods
-
+    end
   end
 end