datagrid 1.6.3 → 1.8.0

data/lib/datagrid/core.rb

@@ -4,27 +4,29 @@ require "active_support/core_ext/class/attribute"
 module Datagrid
   module Core
 
+    # @!visibility private
     def self.included(base)
-      base.extend         ClassMethods
+      base.extend ClassMethods
       base.class_eval do
         class_attribute :scope_value
 
         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)
           include ::ActiveModel::AttributeAssignment
         end
       end
-      base.send :include, InstanceMethods
-    end # self.included
+      base.include InstanceMethods
+    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
@@ -49,17 +56,28 @@ module Datagrid
           }
           self
         else
-          check_scope_defined!
-          scope_value.call
+          scope = original_scope
+          driver.to_scope(scope)
         end
       end
 
-      def driver #:nodoc:
-        @driver ||= Drivers::AbstractDriver.guess_driver(scope).new
+      # @!visibility private
+      def original_scope
+        check_scope_defined!
+        scope_value.call
+      end
+
+      # @!visibility private
+      def driver
+        @driver ||= Drivers::AbstractDriver.guess_driver(scope_value.call).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 +87,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 +116,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 +127,7 @@ module Datagrid
         child_class.datagrid_attributes = self.datagrid_attributes.clone
       end
 
-    end # ClassMethods
+    end
 
     module InstanceMethods
 
@@ -122,8 +144,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 +153,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)
+        scope
       end
 
-
       # Updates datagrid attributes with a passed hash argument
       def attributes=(attributes)
         if respond_to?(:assign_attributes)
@@ -163,7 +187,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 +198,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 +208,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
@@ -205,29 +228,39 @@ module Datagrid
           }
           self
         else
-          check_scope_defined!
-          scope_value.call
+          scope = original_scope
+          driver.to_scope(scope)
         end
       end
 
+      # @!visibility private
+      def original_scope
+        check_scope_defined!
+        scope_value.call
+      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 +273,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)
@@ -18,7 +19,7 @@ module Datagrid
         # We can only reveal it by checking if it respond to some specific
         # to ActiveRecord method like #scoped
         if scope.is_a?(Class)
-          Rails.version >= "4.0" ? scope.all : scope.scoped({})
+          scope.all
         elsif scope.respond_to?(:scoped)
           scope.scoped
         else
@@ -42,7 +43,7 @@ module Datagrid
       end
 
       def asc(scope, order)
-        # Rails 3.x.x don't able to override already applied order
+        # Relation#order isn't able to override already applied order
         # Using #reorder instead
         scope.reorder(order)
       end

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)
@@ -81,8 +82,12 @@ module Datagrid
       end
 
       def batch_each(scope, batch_size, &block)
-        scope.extension(:pagination).each_page(batch_size) do |page|
-          page.each(&block)
+        if scope.opts[:limit]
+          scope.each(&block)
+        else
+          scope.extension(:pagination).each_page(batch_size) do |page|
+            page.each(&block)
+          end
         end
       end
 

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,8 +1,12 @@
+# 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
 
+  class_attribute :input_helper_name, instance_writer: false
   attr_accessor :grid_class, :options, :block, :name
 
   def initialize(grid_class, name, options = {}, &block)
@@ -26,7 +30,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)
@@ -169,8 +173,8 @@ class Datagrid::Filters::BaseFilter #:nodoc:
 
   def default_filter(value, scope, grid)
     return nil if dummy?
-    if !driver.has_column?(scope, name) && driver.to_scope(scope).respond_to?(name)
-      driver.to_scope(scope).send(name, value)
+    if !driver.has_column?(scope, name) && scope.respond_to?(name)
+      scope.send(name, value)
     else
       default_filter_where(scope, value)
     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,18 +1,19 @@
 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 = {})
+          Utils.warn_once('date_range_filters is deprecated in favor of range option for date filter')
           from_options = normalize_composite_filter_options(from_options, field)
           to_options = normalize_composite_filter_options(to_options, field)
 
@@ -25,6 +26,7 @@ module Datagrid
         end
 
         def integer_range_filters(field, from_options = {}, to_options = {})
+          Utils.warn_once('integer_range_filters is deprecated in favor of range option for integer filter')
           from_options = normalize_composite_filter_options(from_options, field)
           to_options = normalize_composite_filter_options(to_options, field)
           filter(from_options[:name] || :"from_#{field.to_s.tr('.', '_')}", :integer, **from_options) do |value, scope, grid|
@@ -37,17 +39,11 @@ module Datagrid
 
         def normalize_composite_filter_options(options, field)
           if options.is_a?(String) || options.is_a?(Symbol)
-            options = {:name => options}
+            options = {name: options}
           end
           options
         end
-      end # ClassMethods
-
-      module InstanceMethods
-
-
-      end # InstanceMethods
-
+      end
     end
   end
 end

data/lib/datagrid/filters/dynamic_filter.rb

@@ -80,7 +80,7 @@ class Datagrid::Filters::DynamicFilter < Datagrid::Filters::BaseFilter
 
   def operations_select
     operations.map do |operation|
-      [I18n.t(operation, :scope => "datagrid.filters.dynamic.operations").html_safe, operation]
+      [I18n.t(operation, scope: "datagrid.filters.dynamic.operations").html_safe, operation]
     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