datagrid 1.6.3 → 1.7.0

data/lib/datagrid/core.rb

@@ -4,6 +4,7 @@ require "active_support/core_ext/class/attribute"
 module Datagrid
   module Core
 
+    # @!visibility private
     def self.included(base)
       base.extend         ClassMethods
       base.class_eval do
@@ -12,7 +13,7 @@ module Datagrid
         class_attribute :datagrid_attributes, instance_writer: false
         self.datagrid_attributes = []
 
-        class_attribute :dynamic_block, :instance_writer => false
+        class_attribute :dynamic_block, instance_writer: false
         class_attribute :forbidden_attributes_protection, instance_writer: false
         self.forbidden_attributes_protection = false
         if defined?(::ActiveModel::AttributeAssignment)
@@ -20,11 +21,12 @@ module Datagrid
         end
       end
       base.send :include, InstanceMethods
-    end # self.included
+    end
 
     module ClassMethods
 
-      def datagrid_attribute(name, &block) #:nodoc:
+      # @!visibility private
+      def datagrid_attribute(name, &block)
         unless datagrid_attributes.include?(name)
           block ||= lambda do |value|
             value
@@ -41,6 +43,11 @@ module Datagrid
       end
 
       # Defines a scope at class level
+      # @return [void]
+      # @example
+      #   scope { User }
+      #   scope { Project.where(deleted: false) }
+      #   scope { Project.preload(:stages) }
       def scope(&block)
         if block
           current_scope = scope_value
@@ -54,12 +61,17 @@ module Datagrid
         end
       end
 
-      def driver #:nodoc:
+      # @!visibility private
+      def driver
         @driver ||= Drivers::AbstractDriver.guess_driver(scope).new
       end
 
       # Allows dynamic columns definition, that could not be defined at class level
-      #
+      # Columns that depend on the database state or third party service
+      # can be defined this way.
+      # @param block [Proc] block that defines dynamic columns
+      # @return [void]
+      # @example
       #   class MerchantsGrid
       #
       #     scope { Merchant }
@@ -69,12 +81,15 @@ module Datagrid
       #     dynamic do
       #       PurchaseCategory.all.each do |category|
       #         column(:"#{category.name.underscore}_sales") do |merchant|
-      #           merchant.purchases.where(:category_id => category.id).count
+      #           merchant.purchases.where(category_id: category.id).count
       #         end
       #       end
       #     end
       #   end
       #
+      #   ProductCategory.create!(name: 'Swimwear')
+      #   ProductCategory.create!(name: 'Sportswear')
+      #
       #   grid = MerchantsGrid.new
       #   grid.data # => [
       #             #      [ "Name",   "Swimwear Sales", "Sportswear Sales", ... ]
@@ -95,6 +110,7 @@ module Datagrid
       end
 
       protected
+
       def check_scope_defined!(message = nil)
         message ||= "#{self}.scope is not defined"
         raise(Datagrid::ConfigurationError, message) unless scope_value
@@ -105,7 +121,7 @@ module Datagrid
         child_class.datagrid_attributes = self.datagrid_attributes.clone
       end
 
-    end # ClassMethods
+    end
 
     module InstanceMethods
 
@@ -122,8 +138,7 @@ module Datagrid
         end
       end
 
-      # Returns a hash of grid attributes including filter values
-      # and ordering values
+      # @return [Hash<Symbol, Object>] grid attributes including filter values and ordering values
       def attributes
         result = {}
         self.datagrid_attributes.each do |name|
@@ -132,21 +147,24 @@ module Datagrid
         result
       end
 
-      # Alias for <tt>send</tt> method
+      # @return [Object] Any datagrid attribute value
       def [](attribute)
         self.send(attribute)
       end
 
+      # Assigns any datagrid attribute
+      # @param attribute [Symbol, String] Datagrid attribute name
+      # @param value [Object] Datagrid attribute value
+      # @return [void]
       def []=(attribute, value)
         self.send(:"#{attribute}=", value)
       end
 
-      # Returns a scope(e.g ActiveRecord::Relation) with all applied filters
+      # @return [Object] a scope relation (e.g ActiveRecord::Relation) with all applied filters
       def assets
         driver.to_scope(scope)
       end
 
-
       # Updates datagrid attributes with a passed hash argument
       def attributes=(attributes)
         if respond_to?(:assign_attributes)
@@ -163,7 +181,7 @@ module Datagrid
       end
 
       # Returns serializable query arguments skipping all nil values
-      #
+      # @example
       #   grid = ProductsGrid.new(category: 'dresses', available: true)
       #   grid.as_query # => {category: 'dresses', available: true}
       def as_query
@@ -174,8 +192,8 @@ module Datagrid
         attributes
       end
 
-      # Returns query parameters to link this grid from a page
-      #
+      # @return [Hash<Symbol, Hash<Symbol, Object>>] query parameters to link this grid from a page
+      # @example
       #   grid = ProductsGrid.new(category: 'dresses', available: true)
       #   Rails.application.routes.url_helpers.products_path(grid.query_params)
       #     # => "/products?products_grid[category]=dresses&products_grid[available]=true"
@@ -184,19 +202,18 @@ module Datagrid
       end
 
       # Redefines scope at instance level
-      #
+      # @example
       #   class MyGrid
       #     scope { Article.order('created_at desc') }
       #   end
       #
       #   grid = MyGrid.new
       #   grid.scope do |scope|
-      #     scope.where(:author_id => current_user.id)
+      #     scope.where(author_id: current_user.id)
       #   end
       #   grid.assets
       #       # => SELECT * FROM articles WHERE author_id = ?
       #       #    ORDER BY created_at desc
-      #
       def scope(&block)
         if block_given?
           current_scope = scope
@@ -211,23 +228,27 @@ module Datagrid
       end
 
       # Resets current instance scope to default scope defined in a class
+      # @return [void]
       def reset_scope
         self.scope_value = self.class.scope_value
       end
 
-      # Returns true if the scope was redefined for this instance of grid object
+      # @return [Boolean] true if the scope was redefined for this instance of grid object
       def redefined_scope?
         self.class.scope_value != scope_value
       end
 
-      def driver #:nodoc:
+      # @!visibility private
+      def driver
         self.class.driver
       end
 
-      def check_scope_defined!(message = nil) #:nodoc:
+      # @!visibility private
+      def check_scope_defined!(message = nil)
         self.class.send :check_scope_defined!, message
       end
 
+      # @return [String] a datagrid attributes and their values in inspection form
       def inspect
         attrs = attributes.map do |key, value|
           "#{key}: #{value.inspect}"
@@ -240,6 +261,6 @@ module Datagrid
           attributes == other.attributes &&
           scope == other.scope
       end
-    end # InstanceMethods
+    end
   end
 end

data/lib/datagrid/drivers/abstract_driver.rb

@@ -1,6 +1,7 @@
 module Datagrid
   module Drivers
-    class AbstractDriver #:nodoc:
+    # @!visibility private
+    class AbstractDriver
 
       TIMESTAMP_CLASSES = [DateTime, Time, ActiveSupport::TimeWithZone]
 

data/lib/datagrid/drivers/active_record.rb

@@ -1,6 +1,7 @@
 module Datagrid
   module Drivers
-    class ActiveRecord < AbstractDriver #:nodoc:
+    # @!visibility private
+    class ActiveRecord < AbstractDriver
 
       def self.match?(scope)
         return false unless defined?(::ActiveRecord)

data/lib/datagrid/drivers/array.rb

@@ -1,6 +1,7 @@
 module Datagrid
   module Drivers
-    class Array < AbstractDriver #:nodoc:
+    # @!visibility private
+    class Array < AbstractDriver
 
       def self.match?(scope)
         !Datagrid::Drivers::ActiveRecord.match?(scope) && (scope.is_a?(::Array) || scope.is_a?(Enumerator))

data/lib/datagrid/drivers/mongo_mapper.rb

@@ -1,6 +1,7 @@
 module Datagrid
   module Drivers
-    class MongoMapper < AbstractDriver #:nodoc:
+    # @!visibility private
+    class MongoMapper < AbstractDriver
 
       def self.match?(scope)
         return false unless defined?(::MongoMapper)

data/lib/datagrid/drivers/mongoid.rb

@@ -1,6 +1,7 @@
 module Datagrid
   module Drivers
-    class Mongoid < AbstractDriver #:nodoc:
+    # @!visibility private
+    class Mongoid < AbstractDriver
 
       def self.match?(scope)
         return false unless defined?(::Mongoid)
@@ -63,7 +64,7 @@ module Datagrid
         return nil unless type
         {
           [BigDecimal , String, Symbol, Range, Array, Hash, ] => :string,
-          [Boolean] => :boolean,
+          [::Mongoid::Boolean] => :boolean,
 
           [Date] => :date,
 

data/lib/datagrid/drivers/sequel.rb

@@ -1,6 +1,7 @@
 module Datagrid
   module Drivers
-    class Sequel < AbstractDriver #:nodoc:
+    # @!visibility private
+    class Sequel < AbstractDriver
 
       def self.match?(scope)
         return false unless defined?(::Sequel)

data/lib/datagrid/drivers.rb

@@ -7,6 +7,7 @@ require "datagrid/drivers/sequel"
 
 
 module Datagrid
-  module Drivers # :nodoc:
+  # @!visibility private
+  module Drivers
   end
 end

data/lib/datagrid/engine.rb

@@ -1,12 +1,13 @@
 require "rails/engine"
 
 module Datagrid
+  # @!private
   class Engine < ::Rails::Engine
     initializer "datagrid.helpers" do
       #TODO: check why it doesn't work
       ActiveSupport.on_load :action_view do
         include Datagrid::Helper
-      end 
-    end 
+      end
+    end
   end
 end

data/lib/datagrid/filters/base_filter.rb

@@ -1,7 +1,10 @@
+# An error raise when datagrid filter is defined incorrectly and
+# causes filtering chain to be broken
 class Datagrid::FilteringError < StandardError
 end
 
-class Datagrid::Filters::BaseFilter #:nodoc:
+# @!visibility private
+class Datagrid::Filters::BaseFilter
 
   attr_accessor :grid_class, :options, :block, :name
 
@@ -26,7 +29,7 @@ class Datagrid::Filters::BaseFilter #:nodoc:
     result = execute(value, scope, grid_object)
 
     return scope unless result
-    if result.is_a?(Datagrid::Filters::DefaultFilterScope)
+    if result == Datagrid::Filters::DEFAULT_FILTER_BLOCK
       result = default_filter(value, scope, grid_object)
     end
     unless grid_object.driver.match?(result)

data/lib/datagrid/filters/boolean_enum_filter.rb

@@ -1,17 +1,19 @@
-class Datagrid::Filters::BooleanEnumFilter < Datagrid::Filters::EnumFilter #:nodoc:
+# @!visibility private
+class Datagrid::Filters::BooleanEnumFilter < Datagrid::Filters::EnumFilter
 
   YES = "YES"
   NO = "NO"
 
   def initialize(report, attribute, options = {}, &block)
+    Datagrid::Utils.warn_once("Datagrid eboolean filter is deprecated in favor of xboolean filter")
     options[:select] = [YES, NO].map do |key, value|
-      [I18n.t("datagrid.filters.eboolean.#{key.downcase}", :default => key.downcase.capitalize), key]
+      [I18n.t("datagrid.filters.eboolean.#{key.downcase}", default: key.downcase.capitalize), key]
     end
     super(report, attribute, options, &block)
   end
 
 
   def checkbox_id(value)
-    [object_name, name, value].join('_').underscore 
+    [object_name, name, value].join('_').underscore
   end
 end

data/lib/datagrid/filters/boolean_filter.rb

@@ -1,5 +1,6 @@
 require "datagrid/utils"
-class Datagrid::Filters::BooleanFilter < Datagrid::Filters::BaseFilter #:nodoc:
+# @!visibility private
+class Datagrid::Filters::BooleanFilter < Datagrid::Filters::BaseFilter
 
   def parse(value)
     Datagrid::Utils.booleanize(value)

data/lib/datagrid/filters/composite_filters.rb

@@ -1,15 +1,15 @@
 module Datagrid
   module Filters
-    module CompositeFilters #:nodoc:
+    # @!visibility private
+    module CompositeFilters
 
       def self.included(base)
         base.extend         ClassMethods
         base.class_eval do
-
         end
-        base.send :include, InstanceMethods
-      end # self.included
+      end
 
+      # @!visibility private
       module ClassMethods
 
         def date_range_filters(field, from_options = {}, to_options = {})
@@ -41,13 +41,7 @@ module Datagrid
           end
           options
         end
-      end # ClassMethods
-
-      module InstanceMethods
-
-
-      end # InstanceMethods
-
+      end
     end
   end
 end

data/lib/datagrid/filters/extended_boolean_filter.rb

@@ -1,4 +1,5 @@
-class Datagrid::Filters::ExtendedBooleanFilter < Datagrid::Filters::EnumFilter #:nodoc:
+# @!visibility private
+class Datagrid::Filters::ExtendedBooleanFilter < Datagrid::Filters::EnumFilter
 
   YES = "YES"
   NO = "NO"

data/lib/datagrid/filters/select_options.rb

@@ -1,5 +1,4 @@
 module Datagrid::Filters::SelectOptions
-
   def select(object)
     select = self.options[:select]
     if select.is_a?(Symbol)
@@ -11,6 +10,18 @@ module Datagrid::Filters::SelectOptions
     end
   end
 
+  def select_values(object)
+    options = select(object)
+    groups_used = grouped_choices?(options)
+    options.map do |option|
+      if groups_used
+        option[1].map {|o| option_text_and_value(o)}
+      else
+        option_text_and_value(option)
+      end
+    end.map(&:last)
+  end
+
   def include_blank
     unless prompt
       options.has_key?(:include_blank) ?
@@ -21,4 +32,26 @@ module Datagrid::Filters::SelectOptions
   def prompt
     options.has_key?(:prompt) ? Datagrid::Utils.callable(options[:prompt]) : false
   end
+
+  protected
+
+  # Rails built-in method:
+  # https://github.com/rails/rails/blob/94e80269e36caf7b2d22a7ab68e6898d3a824122/actionview/lib/action_view/helpers/form_options_helper.rb#L789
+  # Code reuse is difficult, so it is easier to duplicate it
+  def option_text_and_value(option)
+    # Options are [text, value] pairs or strings used for both.
+    if !option.is_a?(String) && option.respond_to?(:first) && option.respond_to?(:last)
+      option = option.reject { |e| Hash === e } if Array === option
+      [option.first, option.last]
+    else
+      [option, option]
+    end
+  end
+
+  # Rails built-in method:
+  # https://github.com/rails/rails/blob/f95c0b7e96eb36bc3efc0c5beffbb9e84ea664e4/actionview/lib/action_view/helpers/tags/select.rb#L36
+  # Code reuse is difficult, so it is easier to duplicate it
+  def grouped_choices?(choices)
+    !choices.blank? && choices.first.respond_to?(:last) && Array === choices.first.last
+  end
 end

data/lib/datagrid/filters.rb

@@ -31,10 +31,10 @@ module Datagrid
       :dynamic => Filters::DynamicFilter
     }
 
-    class DefaultFilterScope
-    end
+    DEFAULT_FILTER_BLOCK = Object.new
 
-    def self.included(base) #:nodoc:
+    # @!visibility private
+    def self.included(base)
       base.extend         ClassMethods
       base.class_eval do
 
@@ -45,13 +45,18 @@ module Datagrid
 
       end
       base.send :include, InstanceMethods
-    end # self.included
+    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
@@ -108,7 +113,7 @@ module Datagrid
       end
 
       def default_filter
-        DefaultFilterScope.new
+        DEFAULT_FILTER_BLOCK
       end
 
       def inspect
@@ -132,11 +137,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 +150,8 @@ module Datagrid
         super(*args, &block)
       end
 
-      def assets # :nodoc:
+      # @!visibility private
+      def assets
         apply_filters(super, filters)
       end
 
@@ -178,11 +185,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 +212,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,8 +2,12 @@ require "action_view"
 
 module Datagrid
   module FormBuilder
-
-    # Returns a form input html for the corresponding filter name
+    # @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, options = {}, &block)
       filter = datagrid_get_filter(filter_or_attribute)
       options = {
@@ -15,7 +19,10 @@ module Datagrid
       self.send(filter.form_builder_helper_name, filter, options, &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)