module Acts::DataTable::ScopeFilters::ActiveRecord::ClassMethods

Public Instance Methods

has_scope_filter(group, scope, options = {}) click to toggle source

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]
# File lib/acts_as_data_table/scope_filters/active_record.rb, line 72
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
has_scope_filters(group, *scopes) click to toggle source

Registers multiple simple filters at once. Important: This does not allow setting validations, custom captions or any other customization options.

# File lib/acts_as_data_table/scope_filters/active_record.rb, line 116
def has_scope_filters(group, *scopes)
  scopes.each do |s|
    has_scope_filter(group, s)
  end
end