acts_as_data_table 0.0.1

data/lib/acts_as_data_table/scope_filters/active_record.rb

@@ -0,0 +1,264 @@
+module Acts
+  module DataTable
+    module ScopeFilters
+      module ActiveRecord
+        def self.included(base)
+          base.send :extend, ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # Generates a scope filter in the given group, meaning that only one of the
+          # filters in the same group may be active at one time.
+          #
+          # @param [String, Symbol] group
+          #   The group name the new filter should be generated in
+          #
+          # @param [String, Symbol] scope
+          #   The scope name the filter depends on
+          #
+          # @param [Hash] options
+          #   Additional options to customize the generated filter
+          #
+          # ----
+          #
+          # @option options [Array<String, Symbol>] :args ([])
+          #   Arguments needed by the scope. This is the case if the scope consists
+          #   of a lambda object.
+          #   The argument names have to be given in the same order as the scope function's
+          #   formal parameters.
+          #
+          # @option options [Symbol, String, Proc] :caption (nil)
+          #   The caption displayed if the filter is used in the application
+          #   The caption is either hardcoded or interpreted based on the given type:
+          #
+          #   - String: The given string is used as is
+          #   - Symbol: The system expects a function with the given name to be defined in the current model.
+          #             It is called with 3 arguments:
+          #               1. The group name
+          #               2. The scope name
+          #               3. The arguments the scope was called with (if any)
+          #   - Proc: The given proc is executed with a hash containing the given arguments (if any)
+          #
+          #   If nothing is given, the default caption is used, meaining the system will use I18n.t
+          #   to search for a defined scope name within the scope 'activerecord.scope_filters.scopes.model.SCOPE'
+          #   Possible scope arguments are passed in as strings
+          #
+          # @option options [Proc, Symbol] :validate (nil)
+          #   A validation method for the scope filter. The filter is only applied if the validation method returns +true+
+          #   This is useful if e.g. a scope needs two dates to work correctly and should only be applied
+          #   if the dates have the correct format.
+          #   If a Symbol is given, the system expects a method with that name
+          #   to be defined as class method in the model class.
+          #
+          #   The validation method is supposed to return an Array<String>
+          #   containing the error messages or a simple boolean value.
+          #
+          # ----
+          #
+          # @example A filter group for locked and not locked records, expecting the scopes :locked and :not_locked to be present.
+          #
+          #     has_scope_filter :status, :locked
+          #     has_scope_filter :status, :not_locked
+          #
+          # @example A full text search with one argument (scope: full_text, formal parameter: text)
+          #
+          #     has_scope_filter :quick_search, :full_text, [:text]
+          #
+          # @example A date range filter
+          #
+          #     has_scope_filter :date, :between, [:start_date, :end_date]
+          #
+          def has_scope_filter(group, scope, options = {})
+            #Load additional helper methods into the model class
+            extend Acts::DataTable::ScopeFilters::ActiveRecord::OnDemand
+
+            model = self
+
+            unless scopes.has_key?(:with_scope_filters)
+              # Generate the named scope which will handle the dynamically given filters
+              # A filter is only applied if a given validation method returns +true+
+              #
+              # Usually, the filters are automatically fetched from the current
+              # thread space, however, in some cases it might be necessary to pass
+              # them in manually (e.g. when using a delayed job to fetch records).
+              # Please only do this if it is really necessary.
+              named_scope :with_scope_filters, lambda {|*args|
+                filters   = args.first
+                filters ||= Acts::DataTable::ScopeFilters::ActionController.get_request_filters
+
+                scope_chain = self
+                filters.each do |group_name, (scope, args)|
+
+                  #Filters should already be validated when they are added through
+                  #the controller, this check is to ensure that no invalid filter is
+                  #ever applied to the model as final protection.
+                  # TODO: Check if the filter is causing an exception (probably through a wrong valiation method)
+                  #       And remove it in this case, adding an error to the log or the module.
+                  if Acts::DataTable::ScopeFilters::Validator.new(model, group_name, scope, args).valid?
+                    actual_args = Acts::DataTable::ScopeFilters::ActiveRecord.actual_params(model, group_name, scope, args)
+                    scope_chain = scope_chain.send(scope, *actual_args)
+                  end
+                end
+
+                results = Acts::DataTable.lookup_nested_hash(scope_chain.current_scoped_methods, :find)
+                results || {}
+              }
+            end
+
+            Acts::DataTable::ScopeFilters::ActiveRecord.register_filter(self, group, scope, options)
+          end
+
+          #
+          # Registers multiple simple filters at once.
+          # Important: This does not allow setting validations, custom captions or any other customization options.
+          #
+          def has_scope_filters(group, *scopes)
+            scopes.each do |s|
+              has_scope_filter(group, s)
+            end
+          end
+        end
+
+
+        #
+        # This module is only included if at least one filter group was added to the model
+        # to avoid pollution in other models.
+        #
+        module OnDemand
+
+        end
+
+        def self.registered_filters
+          @@registered_filters ||= {}
+        end
+
+        #
+        # Registers a filter in the system which is then accessed when applying filters through a scope
+        # The filters are kept in this module as it can be accessed from everywhere,
+        # while a model class may not be known from within these methods.
+        #
+        # @param [ActiveRecord::Base] model
+        #   The model class the scope to be added belongs to
+        #
+        # @param [String, Symbol] group
+        #   The group name the scope belongs to within the +model+
+        #
+        # @param [String, Symbol] scope
+        #   The scope name, it has to be a valid (named) scope within +model+
+        #
+        # @param [Hash] options
+        #   Filter options, see #has_scope_filter
+        #
+        def self.register_filter(model, group, scope, options)
+          unless model.scopes.has_key?(scope.to_sym)
+            raise ArgumentError.new "The scope '#{scope}' in group '#{group}' does not exist in the model class '#{model.to_s}'"
+          end
+
+          Acts::DataTable.ensure_nested_hash!(self.registered_filters, model.to_s, group.to_s)
+          self.registered_filters[model.to_s][group.to_s][scope.to_s] = options
+        end
+
+        #
+        # @see #register_filter for arguments
+        #
+        # @return [Hash, NilClass] options given for the chosen filter if available
+        #
+        def self.filter_options(model, group, scope)
+          res = Acts::DataTable.lookup_nested_hash(self.registered_filters, model.to_s, group.to_s, scope.to_s)
+          unless res
+            raise ArgumentError.new("The scope '#{scope}' was expected to be defined in group '#{group}' of model '#{model}' but couldn't be found.")
+          end
+          res
+        end
+
+        #
+        # @return [Array<String, Symbol>] the args set up when registering the given filter
+        #
+        # @see #filter_options for parameters
+        #
+        def self.filter_args(*args)
+          self.filter_options(*args)[:args] || []
+        end
+
+        #
+        # @return [Fixnum] the amount of formal parameters the scope is defined with
+        #   Note that this will return 0 for no formal parameters which differs to the way
+        #   ruby 1.8 handles lambda expressions (returning -1)
+        #
+        # @see #filter_options for parameters
+        #
+        def self.filter_arity(*args)
+          self.filter_args(*args).size
+        end
+
+        #
+        # @return [TrueClass, FalseClass] +true+ if the given filter was actually registered before.
+        #
+        # @see #filter_options for parameters
+        #
+        def self.registered_filter?(*args)
+          !!(self.filter_options(*args))
+        end
+
+        #
+        # Checks whether the given argument count matches the given scope filter's formal
+        # parameter count.
+        #
+        # @return [TrueClass, FalseClass] +true+ if the given argument count is
+        #   sufficient for the chosen filter.
+        #
+        def self.matching_arity?(model, group, scope, arg_count)
+          self.filter_arity(model, group, scope) == arg_count
+        end
+
+        #
+        # @return [String] The scope filter caption for the given scope
+        # @see #has_scope_filter for more information about how the caption is generated.
+        #
+        def self.scope_filter_caption(model, group, scope, args)
+          args ||= {}
+
+          case caption = self.filter_options(model, group, scope)[:caption]
+          when String
+            caption
+          when Symbol
+            if model.respond_to?(caption)
+              model.send(caption, group, scope, args)
+            else
+              raise ArgumentError.new "The method '#{caption}' was set up as scope filter caption method in model '#{model.name}', but doesn't exist."
+            end
+          when Proc
+            caption.call(args)
+          else
+            options = {:scope => "activerecord.scope_filters.scopes.#{model.name.underscore}"}
+            options.merge!(args.symbolize_keys)
+            I18n.t(scope, options)
+          end
+        end
+
+        #
+        # @return [Array<Object>] The actual parameters for a scope call
+        #   based on the registered filter and the given arguments.
+        #   This method should be used to ensure the correct order
+        #   of arguments when applying a scope.
+        #
+        # @example Actual parameter generation for a date range scope
+        #
+        #   #has_scope_filter :date, :between, [:start_date, :end_date]
+        #   actual_params(model, :date, :between, {:end_date => '2015-04-01', :start_date => '2015-03-01'})
+        #   #=> ['2015-03-01', '2015-04-01']
+        #
+        def self.actual_params(model, group, scope, args)
+          res = []
+          self.filter_args(model, group, scope).each do |arg_name|
+            res << args.stringify_keys[arg_name.to_s]
+          end
+          res
+        end
+
+
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/scope_filters/form_helper.rb

@@ -0,0 +1,67 @@
+module Acts
+  module DataTable
+    module ScopeFilters
+      class FormHelper
+        def initialize(action_view, group, scope)
+          @action_view = action_view
+          @group       = group.to_s
+          @scope       = scope.to_s
+        end
+
+        def text_field(arg, options = {})
+          value        = options.delete(:value) || current_arg(arg)
+          options[:id] = FormHelper.field_id(@group, @scope, arg)
+          @action_view.text_field_tag(FormHelper.field_name(arg), value, options)
+        end
+
+        #
+        # @return [TrueClass, FalseClass] +true+ if the current filter is currently active
+        #
+        def active?
+          @action_view.acts_as_data_table_session.active_filter(@group) == @scope
+        end
+
+        #
+        # @return [String] The URL to remove the current filter group from the active filters
+        #
+        def remove_url
+          @action_view.url_for({:scope_filters => {:action => 'remove', :group => @group}})
+        end
+
+        #
+        # @return [Array] Filter validation errors on the current group
+        #
+        def errors
+          @action_view.acts_as_data_table_session.errors_on(@group)
+        end
+
+        #
+        # @return [String] A generated field name for the given arg to be used in filter forms
+        #
+        def self.field_name(arg)
+          "scope_filters[args][#{arg}]"
+        end
+
+        #
+        # @return [String] A generated DOM id for the given group, scope and arg
+        #
+        def self.field_id(group, scope, arg)
+          [group, scope, arg].map(&:to_s).join('_')
+        end
+
+        private
+
+        #
+        # Retrieves the current value for the given arg name from the session.
+        # Also searches the current request's params if the arg couldn't be found in the session.
+        # This is useful to keep given values in case of validation errors.
+        #
+        def current_arg(arg)
+          Acts::DataTable.lookup_nested_hash(@action_view.acts_as_data_table_session.active_filters, @group, @scope.to_s, arg.to_s) ||
+              Acts::DataTable.lookup_nested_hash(@action_view.params, :scope_filters, :args, arg)
+        end
+
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/scope_filters/validator.rb

@@ -0,0 +1,144 @@
+module Acts
+  module DataTable
+    module ScopeFilters
+      class Validator
+
+        def initialize(model, group, scope, args)
+          @model = model
+          @group = group
+          @scope = scope
+          @args  = args
+        end
+
+        #
+        # Validates the given scope filter and returns possible error messages
+        #
+        # @see {Acts::DataTable::ScopeFilters::ActiveRecord}#register_filter for arguments
+        #
+        def validate
+          validations = Acts::DataTable::ScopeFilters::ActiveRecord.filter_options(@model, @group, @scope)[:validate]
+
+          Array(validations).inject([]) do |res, proc|
+            res += run_validation(proc)
+            res
+          end.uniq.compact
+        end
+
+        def valid?
+          validate.empty?
+        end
+
+        private
+
+        #----------------------------------------------------------------
+        #                      Built-in Validations
+        #----------------------------------------------------------------
+
+        #
+        # @return [TrueClass, FalseClass] +true+ if the given validation
+        #  is a built-in one.
+        #
+        def built_in_validation?(validation_name)
+          private_methods.include?("validate_#{validation_name}")
+        end
+
+        #
+        # Runs a built-in validation
+        #
+        def built_in_validation(validation_name)
+          send("validate_#{validation_name}")
+        end
+
+        #
+        # Each of the given arguments has to be parseable by Date.parse
+        #
+        def validate_all_dates
+          validate_all :invalid_date do |k, v|
+            Date.parse(v) rescue nil
+          end
+        end
+
+        #
+        # Each of the given arguments has to be present (!blank?)
+        #
+        def validate_all_present
+          validate_all :blank do |k, v|
+            v.present?
+          end
+        end
+
+        #
+        # Validates that all given arguments with names of the format /[a-z]+_id/
+        # actually refer to valid records in the system
+        #
+        def validate_record_existence
+          validate_all :invalid_record do |k, v|
+            m = /([a-z]+)_id/.match(k.to_s)
+            if m
+              model  = m[1].camelize.constantize
+              !!model.find_by_id(v)
+            else
+              true
+            end
+          end
+        end
+
+        #----------------------------------------------------------------
+        #                        Helper Methods
+        #----------------------------------------------------------------
+
+        def run_validation(proc)
+          case proc
+            when Proc
+              result = proc.call(@args)
+            when Symbol
+              if built_in_validation?(proc)
+                result = built_in_validation(proc)
+              elsif @model.respond_to?(proc)
+                result = @model.send(proc, @args)
+              else
+                raise ArgumentError.new "The method '#{@proc}' was set up as scope filter validation method in model '#{@model.name}', but doesn't exist."
+              end
+            when NilClass
+              result = true
+            else
+              raise ArgumentError.new "An invalid validations method was given for the scope '#{@scope}' in group '#{@group}' of model '#{@model.name}'"
+          end
+
+          #If the result is already an array of error messages, we can simply return it.
+          #Otherwise, we have to generate an error array based on the boolean result
+          #the validation method produced.
+          if result.is_a?(Array)
+            result
+          else
+            result ? [] : [Acts::DataTable.t('scope_filters.validations.general_error')]
+          end
+        end
+
+        def validate_all(error, &proc)
+          @args.inject([]) do |res, (k, v)|
+            unless proc.call(k, v)
+              res << Acts::DataTable.t("scope_filters.validations.#{error}", :arg_name => localized_arg_name(k), :arg_value => v)
+            end
+            res
+          end
+        end
+
+        #
+        # Looks up the given argument name in activerecord.scope_filters.args.MODEL.
+        #
+        # If no translation was specified, it behaves like I18n.t in rails 4 and tries
+        # to make the best of the given given argument name
+        #
+        def localized_arg_name(arg_name)
+          l = I18n.t(arg_name, :scope => "activerecord.scope_filters.args.#{@model.to_s.underscore}.#{@scope}")
+          if l =~ /translation missing/
+            arg_name.to_s.split('_').map(&:camelize).join(' ')
+          else
+            l
+          end
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/session_helper.rb

@@ -0,0 +1,193 @@
+module Stex
+  module Acts
+    module DataTable
+      class SessionHelper
+        def initialize(session, controller_path, action, model_name)
+          @session         = session
+          @controller_path = controller_path
+          @action          = action
+          @model           = model_name.to_s.classify.constantize
+        end
+
+        def controller_path
+          @controller_path
+        end
+
+        def action_name
+          @action
+        end
+
+        def model
+          @model
+        end
+
+        #----------------------------------------------------------------
+        #                           Filters
+        #----------------------------------------------------------------
+
+        # Adds a filter for a specific view
+        # If a filter for this group is already set, the new filter
+        # will override the existing one.
+        #--------------------------------------------------------------
+        def add_filter(group, scope, args)
+          controller_key = action_key(controller_path, action_name)
+          @session[:scope_filters] ||= {}
+          @session[:scope_filters][controller_key] ||= {}
+
+          args = hash_keys_to_strings(args) if args
+
+          @session[:scope_filters][controller_key][group.to_s] = {scope.to_s => args}
+        end
+
+        # Removes an active filter. As only one filter per group can
+        # be active at a time, we can simply delete the whole group.
+        # If all filters are deleted, we can also remove the namespaces
+        # in the session
+        #--------------------------------------------------------------
+        def remove_filter(group)
+          controller_key = action_key(controller_path, action_name)
+          return unless @session[:scope_filters][controller_key]
+          @session[:scope_filters][controller_key].delete(group.to_s)
+          @session[:scope_filters].delete(controller_key) if @session[:scope_filters][controller_key].empty?
+          @session.delete(:scope_filters) if @session[:scope_filters].empty?
+        end
+
+        # Removes all filters from the given controller + action
+        #--------------------------------------------------------------
+        def remove_all_filters
+          @session[:scope_filters].delete(action_key(controller_path, action_name))
+        end
+
+        # Returns all active filters for the given controller and action
+        #--------------------------------------------------------------
+        def active_filters
+          return {} unless @session[:scope_filters]
+          @session[:scope_filters][action_key(controller_path, action_name)] || {}
+        end
+
+        # Checks if the given filter is currently active
+        #--------------------------------------------------------------
+        def active_filter?(group, scope, args)
+          active = active_filters
+          args = hash_keys_to_strings(args) if args
+
+          active.any? &&
+              active[group.to_s] &&
+              active[group.to_s].has_key?(scope.to_s) &&
+              (active[group.to_s][scope.to_s].to_a - args.to_a).empty? #sometimes the session hash contains {:raise => true}, whereever it comes from...
+        end
+
+        #----------------------------------------------------------------
+        #                         Column Sorting
+        #----------------------------------------------------------------
+
+        # Replaces all current sorting columns with the new one
+        #--------------------------------------------------------------
+        def replace_sorting_column(model_name, column_name)
+          args = generate_sorting_arguments(model_name, column_name)
+          return unless args[:model].column_names.include?(column_name.to_s)
+
+          @session[:column_sorting] ||= {}
+          @session[:column_sorting][args[:key]] = [[args[:column], 'ASC']]
+        end
+
+        # Adds a new sorting column to the current controller and action
+        #--------------------------------------------------------------
+        def add_or_toggle_sorting_column(model_name, column_name)
+          args = generate_sorting_arguments(model_name, column_name)
+
+          return unless args[:model].column_names.include?(column_name.to_s)
+
+          @session[:column_sorting] ||= {}
+          @session[:column_sorting][args[:key]] ||= []
+
+          existing_entry = @session[:column_sorting][args[:key]].assoc(args[:column])
+
+          #Toggle the direction
+          if existing_entry
+            idx = @session[:column_sorting][args[:key]].index(existing_entry)
+
+            direction = existing_entry.last == 'ASC' ? 'DESC' : 'ASC'
+
+            @session[:column_sorting][args[:key]].delete(existing_entry)
+
+            @session[:column_sorting][args[:key]].insert(idx, [args[:column], direction])
+          else
+            #Simply append the new column to the sorting list
+            @session[:column_sorting][args[:key]] << [args[:column], 'ASC']
+          end
+        end
+
+        # Removes a sorting column from current controller and action
+        #--------------------------------------------------------------
+        def remove_sorting_column(model_name, column_name)
+          args = generate_sorting_arguments(model_name, column_name)
+          return if @session[:column_sorting].nil? || @session[:column_sorting].empty?
+          return unless @session[:column_sorting].has_key?(args[:key])
+
+          existing_entry = @session[:column_sorting][args[:key]].assoc(args[:column])
+          @session[:column_sorting][args[:key]].delete(existing_entry) if existing_entry
+
+          #Remove the controller namespace from the session if it's empty
+          @session[:column_sorting].delete(args[:key]) if @session[:column_sorting][args[:key]].empty?
+        end
+
+        # Returns all sorting columns as a string
+        #--------------------------------------------------------------
+        def sorting_columns_string
+          controller_key = action_key(controller_path, action_name)
+          return nil if @session[:column_sorting].nil? || @session[:column_sorting].empty?
+          return nil unless @session[:column_sorting].has_key?(controller_key)
+
+          @session[:column_sorting][controller_key].map {|column_and_direction| column_and_direction.join(' ')}.join(', ')
+        end
+
+        # Returns the current sorting direction for a given column
+        # or nil if this column is currently not active.
+        #--------------------------------------------------------------
+        def sorting_direction(model_name, column_name)
+          args = generate_sorting_arguments(model_name, column_name)
+
+          return nil if @session[:column_sorting].nil? || @session[:column_sorting].empty?
+          return nil unless @session[:column_sorting].has_key?(args[:key])
+          entry = @session[:column_sorting][args[:key]].assoc(args[:column])
+          entry ? entry.last : nil
+        end
+
+        # loads the sorting defaults for the current action
+        # Parameters==
+        #   defaults:: [['users.last_name', 'ASC'], ['users.first_name', 'ASC']]
+        #--------------------------------------------------------------
+        def load_sorting_defaults(defaults = [])
+          return if defaults.empty?
+          controller_key = action_key(controller_path, action_name)
+          @session[:column_sorting] = {}
+          @session[:column_sorting][controller_key] = defaults
+        end
+
+        private
+
+        def generate_sorting_arguments(model_name, column_name)
+          model = model_name.to_s.classify.constantize
+          {
+              :model  => model,
+              :key    => action_key(controller_path, action_name),
+              :column => "#{model.table_name}.#{column_name}"
+          }
+        end
+
+        def action_key(controller, action)
+          [controller.gsub("/", "_"), action].join('_')
+        end
+
+        def hash_keys_to_strings(hash)
+          new_hash = {}
+          hash.each do |key, value|
+            new_hash[key.to_s] = value
+          end
+          new_hash
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/shared/action_controller.rb

@@ -0,0 +1,25 @@
+module Acts
+  module DataTable
+    module Shared
+      module ActionController
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+
+        end
+
+        module OnDemand
+          def self.included(base)
+            base.helper_method :acts_as_data_table_session
+          end
+
+          def acts_as_data_table_session
+            @acts_as_data_table_session ||= Acts::DataTable::Shared::Session.new(session, controller_path, action_name)
+          end
+        end
+      end
+    end
+  end
+end