filterrific 1.4.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dfb96075da4c30641cdfb5fdf747706a310f0324
-  data.tar.gz: fc4f107545fa2838949eb88be2b0beee14927d14
+  metadata.gz: 5771d0552efaa97955d18305f8199f7691148d93
+  data.tar.gz: 037e7d5b634f6183cd6315d35cdd5a8874c47f3c
 SHA512:
-  metadata.gz: 32d36a46d02d7fd55951b41c05e54022696dcccee1cb184fdf6da63bf469104e8279141a7fd620a4dbb49a24c8f579a58a4646963ef632f3672f75c8478d95b2
-  data.tar.gz: 1d427b2a134182022656d1ef5cc3347e2c3f05d9fdcb4bb81cb8d8ad15a1f0cac7e6266f73670dd979df1afa30433e4ba93ca1ef380837a41ef4f79fa6f0c372
+  metadata.gz: 6da890161d37d8884debfff82b057f1fe304ebcf858b6a0493cc756739428cc33fdc131abd0f174fd4ea449704404adc10204c33fa22d89b96c623001aefdafc
+  data.tar.gz: 192de17ea6192932f6e6c262fa6888fa35b39188ec0c99dcaf76bedd94434671f2754968ac4e9cc0fad8d2fc461c95dbb122e1b11074afc7fe1567b46920258d

data/CHANGELOG.md

@@ -1,12 +1,10 @@
-# 2.0.0
-
-API changes
-
-* Filterrific can build the `sorted_by` and `search_query` scopes automatically,
-  based on some configuration in the including model.
-
+* using the "sorted_by" magic method will add entries to select_options automatically
     filterrific(
-      default_settings: { sorted_by: 'name_asc' },
+      default_filter_params: { sorted_by: 'name_asc' },
+      available_filters: [
+        :with_country,
+        ...
+      ],
       search_query: {
         match_terms: :any, # [:all]
         auto_wildcard: :suffix, # [:prefix, :both, :none]
@@ -17,39 +15,56 @@ API changes
         name_asc: 'Name (A-Z)',
         name_desc: 'Name (Z-A)',
       },
-      scopes: [
+    )
+
+    filterrific(
+      default_filter_params: { sorted_by: 'name_asc' },
+      custom_scopes: [
         :with_country,
         ...
+      ],
+      lookup_filters: [ # column_value_filters:, value_filters:
+        :with_country_id,
+        :with_state,
       ]
+      search_query: {
+        match_terms: :any, # [:all]
+        auto_wildcard: :suffix, # [:prefix, :both, :none]
+        columns: [:first_name, :email, :last_name],
+        case_sensitive: false, # [true]
+      },
+      sorted_by: {
+        name_asc: 'Name (A-Z)',
+        name_desc: 'Name (Z-A)',
+      },
     )
 
-* Filterrific can handle persistence of search params in session for you.
-* Simplified `@filterrific.find` method to load collection from DB.
-  Replaces `Student.filterrific_find(@filterrific)`
 
-    @filterrific = initialize_filterrific(
-      Student,
-      default_settings: {},
-      filter_names: [],
-      params_key: :filterrific,
-      select_options: {},
-      session_persistence_key: 'asdf',
-    )
-    @students = @filterrific.find
 
-* The filterrific form builder now doesn't override the standard
-  `form_for` method. It is used via `form_for_filterrific` instead:
+# 2.0.0
 
-    form_for_filterrific @filterrific do |f|
+API changes:
 
+* Filterrific model API option names have changed.
+* Better initialization of Filterrific via `initialize_filterrific` method:
+    * It resets the filter params, so the `reset_filterrific` action is not required any more.
+    * It persists filter params in session.
+* Simplified `@filterrific.find` method to load collection from DB.
+  Replaces `Student.filterrific_find(@filterrific)`
+* The `form_for_filterrific` form builder doesn't override the standard
+  `form_for` method any more.
 * Dropped support for Ruby 1.8.7 (because of 1.9 Hash syntax)
 * Dropped support for Rails <= 3.0.0 (because of ActiveRecord
   bug fixes in 3.1, and use of asset pipeline)
 
+
+
 ### 1.4.3
 
 * Handle case where Filterrific filter params are empty.
 
+
+
 ### 1.4.2
 
 * Updated initialization of ActiveRecord and ActionView extensions again

data/README.md

@@ -13,8 +13,6 @@ search, and sort your ActiveRecord lists:
 Make sure to go to the fantastic [Filterrific documentation](http://filterrific.clearcove.ca)
 to find out more!
 
-TODO: look at Jeff's email suggestions (June 23, 2014)
-
 ### Installation
 
 `gem install filterrific`
@@ -28,11 +26,11 @@ or with bundler in your Gemfile:
 
 Every commit to Filterrific is automatically tested against the following scenarios:
 
-| Rails version | Ruby environments       | Database adapters                  | Build status |
-|---------------|-------------------------|------------------------------------|--------------|
-| Rails 4.1     | MRI 1.9.3, 2.0.0, 2.1.2 | mysql, mysql2, postgresql, sqlite3 |[![Build Status](https://travis-ci.org/jhund/filterrific_demo.svg?branch=rails-4.1)](https://travis-ci.org/jhund/filterrific_demo)|
-| Rails 4.0     | MRI 1.9.3, 2.0.0, 2.1.2 | mysql, mysql2, postgresql, sqlite3 |[![Build Status](https://travis-ci.org/jhund/filterrific_demo.svg?branch=rails-4.0)](https://travis-ci.org/jhund/filterrific_demo)|
-| Rails 3.2     | MRI 1.9.3, 2.0.0, 2.1.2 | mysql, mysql2, postgresql, sqlite3 |[![Build Status](https://travis-ci.org/jhund/filterrific_demo.svg?branch=rails-3.2)](https://travis-ci.org/jhund/filterrific_demo)|
+| Rails version | Ruby environments              | Database adapters                  | Build status |
+|---------------|--------------------------------|------------------------------------|--------------|
+| Rails 4.1     | MRI 1.9.3, 2.0.0, 2.1.2, 2.2.0 | mysql, mysql2, postgresql, sqlite3 |[![Build Status](https://travis-ci.org/jhund/filterrific_demo.svg?branch=rails-4.1)](https://travis-ci.org/jhund/filterrific_demo)|
+| Rails 4.0     | MRI 1.9.3, 2.0.0, 2.1.2, 2.2.0 | mysql, mysql2, postgresql, sqlite3 |[![Build Status](https://travis-ci.org/jhund/filterrific_demo.svg?branch=rails-4.0)](https://travis-ci.org/jhund/filterrific_demo)|
+| Rails 3.2     | MRI 1.9.3, 2.0.0, 2.1.2        | mysql, mysql2, postgresql, sqlite3 |[![Build Status](https://travis-ci.org/jhund/filterrific_demo.svg?branch=rails-3.2)](https://travis-ci.org/jhund/filterrific_demo)|
 
 Filterrific version 1.4.0 should work on older versions of Rails and Ruby, however
 the 1.x branch is not supported any more.
@@ -65,6 +63,12 @@ I'm happy to help you if you encounter problems when using filterrific. You'll m
 
 [![Code Climate](https://codeclimate.com/github/jhund/filterrific.png)](https://codeclimate.com/github/jhund/filterrific)
 
+### Related projects
+
+* has_scope
+* http://www.justinweiss.com/blog/2014/02/17/search-and-filter-rails-models-without-bloating-your-controller/
+* https://github.com/laserlemon/periscope
+
 ### License
 
 [MIT licensed](https://github.com/jhund/filterrific/blob/master/MIT-LICENSE).

data/lib/filterrific.rb

@@ -1,11 +1,7 @@
+# -*- coding: utf-8 -*-
+
 require 'filterrific/version'
 require 'filterrific/engine'
 
 module Filterrific
-
-  # Wrapper around Filterrific::ParamSet initialization
-  def self.new(a_resource_class, filterrific_params = {})
-    Filterrific::ParamSet.new(a_resource_class, filterrific_params)
-  end
-
 end

data/lib/filterrific/action_controller_extension.rb

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+#
+# Adds Filterrific methods ActionController instances
+#
+module Filterrific
+  module ActionControllerExtension
+
+  protected
+
+    # @param model_class [Class]
+    # @param filterrific_params [Hash] typically the Rails request params under
+    #    the :filterrific key (params[:filterrific]), however can be any Hash.
+    # @param opts [Hash]
+    # @option opts [Array<String>, optional] :available_filters
+    #   further restrict which of the filters specified in the model are
+    #   available in this context.
+    # @option opts [Hash, optional] :default_filter_params
+    #   overrides the defaults specified in the model.
+    # @option opts [String, Symbol, optional] :persistence_id
+    #   defaults to "namespace/controller#action" string, used for session key
+    #   and saved searches to isolate different filters' persisted params from
+    #   each other.
+    # @option opts [Hash, optional] :select_options
+    #   these are available in the view to populate select lists and other
+    #   dynamic values.
+    # @return [Filterrific::ParamSet]
+    def initialize_filterrific(model_class, filterrific_params, opts)
+      f_params = (filterrific_params || {}).deep_stringify_keys
+      opts = opts.stringify_keys
+      pi = opts['persistence_id'] || compute_default_persistence_id
+
+      if (f_params.delete('reset_filterrific'))
+        # Reset query and session_persisted params
+        session[pi] = nil
+        redirect_to url_for({})  and return false # works with `or return` in calling action.
+      end
+
+      f_params = f_params.presence || # start with passed in params
+                 session[pi].presence || # then try session persisted params
+                 opts['default_filter_params'] || # then use passed in opts
+                 model_class.filterrific_default_filter_params # finally use model_class defaults
+
+      f_params.deep_stringify_keys!
+      f_params.slice!(opts['available_filters'].map(&:to_s))  if opts['available_filters']
+
+      filterrific = Filterrific::ParamSet.new(model_class, f_params)
+      filterrific.select_options = opts['select_options']
+      session[pi] = filterrific.to_hash
+      filterrific
+    end
+
+    # Computes a default persistence id based on controller and action name
+    def compute_default_persistence_id
+      [controller_name, action_name].join('#')
+    end
+
+  end
+end

data/lib/filterrific/action_view_extension.rb

@@ -1,23 +1,25 @@
 # -*- coding: utf-8 -*-
-
 #
-# Adds view helpers to ActionView
+# Adds Filterrific view helpers to ActionView instances
 #
 module Filterrific
   module ActionViewExtension
 
-    # Sets all options on form_for to defaults if called with Filterrific object
-    def form_for(record, options = {}, &block)
-      if record.is_a?(Filterrific::ParamSet)
-        options[:as] ||= :filterrific
-        options[:html] ||= {}
-        options[:html][:method] ||= :get
-        options[:html][:id] ||= :filterrific_filter
-        options[:url] ||= url_for(:controller => controller.controller_name, :action => controller.action_name)
-      end
-      super
+    # Sets all options on form_for to defaults that work with Filterrific
+    # @param record [Filterrific] the @filterrific object
+    # @param options [Hash] standard options for form_for
+    # @param block [Proc] the form body
+    def form_for_filterrific(record, options = {}, &block)
+      options[:as] ||= :filterrific
+      options[:html] ||= {}
+      options[:html][:method] ||= :get
+      options[:html][:id] ||= :filterrific_filter
+      options[:url] ||= url_for(
+        :controller => controller.controller_name,
+        :action => controller.action_name
+      )
+      form_for(record, options, &block)
     end
-    # TODO: change this to form_for_filterrific!
 
     # Renders a spinner while the list is being updated
     def render_filterrific_spinner
@@ -27,36 +29,40 @@ module Filterrific
         </span>
       ).html_safe
     end
-    #alias: filterrific_spinner
 
     # Renders a link which indicates the current sorting and which can be used to
     # toggle the list sorting (set column and direction).
+    #
     # NOTE: Make sure that this is used in the list partial that is re-rendered
     # when the filterrific params are changed, so that the filterrific params in
     # the URL are always current.
-    # @param[Filterrific::ParamSet] filterrific the current filterrific instance
-    # @param[String, Symbol] sort_key the key to sort by, without direction.
+    #
+    # NOTE: Currently the filterrific_sorting_link is not synchronized with a
+    # SELECT input you may have in the filter form for sorting. We recommend you
+    # use one or the other to avoid conflicting sort settings in the UI.
+    #
+    # @param filterrific [Filterrific::ParamSet] the current filterrific instance
+    # @param sort_key [String, Symbol] the key to sort by, without direction.
     #     Example: 'name', 'created_at'
-    # @param[Hash, optional] options:
-    #     * active_column_class: CSS class applied to current sort column.
-    #       Default: 'filterrific_current_sort_column'
-    #     * ascending_indicator: HTML string to indicate ascending sort direction.
-    #       Default: Triangle pointing up.
-    #     * default_sort_direction: override the default sorting when selecting
-    #       a new sort column. Default: 'asc'.
-    #     * descending_indicator: HTML string to indicate descending sort direction.
-    #       Default: Triangle pointing down.
-    #     * html_attrs: HTML attributes to be added to the sorting link. Default: {}
-    #     * label: override label. Default: `sort_key.humanize`.
-    #     * sorting_scope_name: override the name of the scope used for sorting.
-    #       Default: `:sorted_by`
-    #     * url_for_attrs: override the target URL attributes to be used for `url_for`.
-    #       Default: {} (current URL).
-    # TODO: update documentation
-    # TODO: update demo app
-    # TODO: synchronize with sorting select in filter
-    def filterrific_sorting_link(filterrific, sort_key, options = {})
-      options = {
+    # @param opts [Hash, optional]
+    # @options opts [String, optional] active_column_class
+    #     CSS class applied to current sort column. Default: 'filterrific_current_sort_column'
+    # @options opts [String, optional] ascending_indicator
+    #     HTML string to indicate ascending sort direction. Default: '⬆'
+    # @options opts [String, optional] default_sort_direction
+    #     Override the default sorting when selecting a new sort column. Default: 'asc'.
+    # @options opts [String, optional] descending_indicator
+    #     HTML string to indicate descending sort direction. Default: '⬇'
+    # @options opts [Hash, optional] html_attrs
+    #     HTML attributes to be added to the sorting link. Default: {}
+    # @options opts [String, optional] label
+    #     Override label. Default: `sort_key.to_s.humanize`.
+    # @options opts [String, Symbol, optional] sorting_scope_name
+    #     Override the name of the scope used for sorting. Default: :sorted_by
+    # @options opts [Hash, optional] url_for_attrs
+    #     Override the target URL attributes to be used for `url_for`. Default: {} (current URL).
+    def filterrific_sorting_link(filterrific, sort_key, opts = {})
+      opts = {
         :active_column_class => 'filterrific_current_sort_column',
         :inactive_column_class => 'filterrific_sort_column',
         :ascending_indicator => '⬆',
@@ -66,52 +72,82 @@ module Filterrific
         :label => sort_key.to_s.humanize,
         :sorting_scope_name => :sorted_by,
         :url_for_attrs => {},
-      }.merge(options)
-      options[:html_attrs] = options[:html_attrs].with_indifferent_access
-      current_sorting = filterrific.send(options[:sorting_scope_name])
-      current_sort_key = current_sorting ? current_sorting.gsub(/_asc|_desc/, '') : nil
-      current_sort_direction = current_sorting ? (current_sorting =~ /_desc\z/ ? 'desc' : 'asc') : nil
+      }.merge(opts)
+      opts.merge!(
+        :html_attrs => opts[:html_attrs].with_indifferent_access,
+        :current_sorting => filterrific.send(opts[:sorting_scope_name]),
+        :current_sort_key => current_sorting ? current_sorting.gsub(/_asc|_desc/, '') : nil,
+        :current_sort_direction => current_sorting ? (current_sorting =~ /_desc\z/ ? 'desc' : 'asc') : nil,
+      )
       new_sort_key = sort_key.to_s
-      if new_sort_key == current_sort_key
-        # current sort column, toggle search_direction
-        new_sort_direction, current_sort_direction_indicator = if 'asc' == current_sort_direction
-          ['desc', options[:ascending_indicator]]
-        else
-          ['asc', options[:descending_indicator]]
-        end
-        new_sorting = [new_sort_key, new_sort_direction].join('_')
-        css_classes = [
-          options[:active_column_class],
-          options[:html_attrs].delete(:class)
-        ].compact.join(' ')
-        new_filterrific_params = filterrific.to_hash
-                                            .with_indifferent_access
-                                            .merge(options[:sorting_scope_name] => new_sorting)
-        url_for_attrs = options[:url_for_attrs].merge(:filterrific => new_filterrific_params)
-        link_to(
-          [options[:label], current_sort_direction_indicator].join(' '),
-          url_for(url_for_attrs),
-          options[:html_attrs].reverse_merge(:class => css_classes, :method => :get, :remote => true)
-        )
+      if new_sort_key == opts[:current_sort_key]
+        # same sort column, reverse order
+        filterrific_sorting_link_reverse_order(filterrific, new_sort_key, opts)
       else
-        # new sort column, change sort column
-        new_sort_direction = options[:default_sort_direction]
-        new_sorting = [new_sort_key, new_sort_direction].join('_')
-        css_classes = [
-          options[:inactive_column_class],
-          options[:html_attrs].delete(:class)
-        ].compact.join(' ')
-        new_filterrific_params = filterrific.to_hash
-                                            .with_indifferent_access
-                                            .merge(options[:sorting_scope_name] => new_sorting)
-        url_for_attrs = options[:url_for_attrs].merge(:filterrific => new_filterrific_params)
-        link_to(
-          options[:label],
-          url_for(url_for_attrs),
-          options[:html_attrs].reverse_merge(:class => css_classes, :method => :get, :remote => true)
-        )
+        # new sort column, default sort order
+        filterrific_sorting_link_new_column(filterrific, new_sort_key, opts)
       end
     end
 
+    # Returns a url that can be used to reset the Filterrific params
+    def reset_filterrific_url(opts = {})
+      url_for(
+        { filterrific: { reset_filterrific: true } }.merge(opts)
+      )
+    end
+
+  protected
+
+    # Renders HTML to reverse sort order on currently sorted column.
+    # @param filterrific [Filterrific::ParamSet]
+    # @param new_sort_key [String]
+    # @param opts [Hash]
+    # @return [String] an HTML fragment
+    def filterrific_sorting_link_reverse_order(filterrific, new_sort_key, opts)
+      # current sort column, toggle search_direction
+      new_sort_direction, current_sort_direction_indicator = if 'asc' == opts[:current_sort_direction]
+        ['desc', opts[:ascending_indicator]]
+      else
+        ['asc', opts[:descending_indicator]]
+      end
+      new_sorting = [new_sort_key, new_sort_direction].join('_')
+      css_classes = [
+        opts[:active_column_class],
+        opts[:html_attrs].delete(:class)
+      ].compact.join(' ')
+      new_filterrific_params = filterrific.to_hash
+                                          .with_indifferent_access
+                                          .merge(opts[:sorting_scope_name] => new_sorting)
+      url_for_attrs = opts[:url_for_attrs].merge(:filterrific => new_filterrific_params)
+      link_to(
+        [opts[:label], opts[:current_sort_direction_indicator]].join(' '),
+        url_for(url_for_attrs),
+        opts[:html_attrs].reverse_merge(:class => css_classes, :method => :get, :remote => true)
+      )
+    end
+
+    # Renders HTML to sort by a new column.
+    # @param filterrific [Filterrific::ParamSet]
+    # @param new_sort_key [String]
+    # @param opts [Hash]
+    # @return [String] an HTML fragment
+    def filterrific_sorting_link_new_column(filterrific, new_sort_key, opts)
+      new_sort_direction = opts[:default_sort_direction]
+      new_sorting = [new_sort_key, new_sort_direction].join('_')
+      css_classes = [
+        opts[:inactive_column_class],
+        opts[:html_attrs].delete(:class)
+      ].compact.join(' ')
+      new_filterrific_params = filterrific.to_hash
+                                          .with_indifferent_access
+                                          .merge(opts[:sorting_scope_name] => new_sorting)
+      url_for_attrs = opts[:url_for_attrs].merge(:filterrific => new_filterrific_params)
+      link_to(
+        opts[:label],
+        url_for(url_for_attrs),
+        opts[:html_attrs].reverse_merge(:class => css_classes, :method => :get, :remote => true)
+      )
+    end
+
   end
 end

data/lib/filterrific/active_record_extension.rb

@@ -1,51 +1,58 @@
+# -*- coding: utf-8 -*-
 #
-# Adds filterrific methods to ActiveRecord::Base and sub classes.
+# Adds Filterrific methods to ActiveRecord::Base model_class.
 #
 require 'filterrific/param_set'
 
 module Filterrific
   module ActiveRecordExtension
 
-    # Adds filterrific behavior to class when called like so:
+    # Adds Filterrific behavior to class when called like so:
     #
     # filterrific(
-    #   :default_settings => { :sorted_by => "created_at_asc" },
-    #   :filter_names => [:sorted_by, :search_query, :with_state]
+    #   :available_filters => [:sorted_by, :search_query, :with_state]
+    #   :default_filter_params => { :sorted_by => "created_at_asc" },
     # )
     #
-    # @params[Hash] options
-    #    Required keys are:
-    #     * :filter_names: a list of filter_names to be exposed by Filterrific
-    #    Optional keys are:
-    #     * :default_settings: default filter settings
-    def filterrific(options)
-      cattr_accessor :filterrific_default_settings
-      cattr_accessor :filterrific_filter_names
-
-      options.stringify_keys!
-
-      assign_filterrific_filter_names(options)
-      validate_filterrific_filter_names
-      assign_filterrific_default_settings(options)
-      validate_filterrific_default_settings
+    # @params opts [Hash] with either string or symbol keys, will be stringified.
+    # @option opts [Array<String, Symbol>] available_filters: a list of filters to be exposed by Filterrific.
+    # @option opts [Hash, optional] default_filter_params: default filter parameters
+    # @return [void]
+    def filterrific(opts)
+      cattr_accessor :filterrific_available_filters
+      cattr_accessor :filterrific_default_filter_params
+      self.filterrific_available_filters = []
+
+      opts.stringify_keys!
+
+      define_sorted_by_scope(opts['sorted_by'])  if opts['sorted_by']
+      #define_search_query_scope(opts['search_query'])  if opts['search_query']
+
+      assign_filterrific_available_filters(opts)
+      validate_filterrific_available_filters
+      assign_filterrific_default_filter_params(opts)
+      validate_filterrific_default_filter_params
+
     end
 
-    # Returns ActiveRecord relation based on given filterrific_param_set.
-    # Use like so:
-    # ModelClass.filterrific_find(@filterrific_param_set)
+    # Returns ActiveRecord relation based on filterrific_param_set.
+    # Use like so: `ModelClass.filterrific_find(@filterrific)`
     #
-    # @param[Filterrific::ParamSet] filterrific_param_set
-    # @return[ActiveRecord::Relation] an ActiveRecord relation.
+    # @param filterrific_param_set [Filterrific::ParamSet]
+    # @return [ActiveRecord::Relation] with filters applied
     def filterrific_find(filterrific_param_set)
       unless filterrific_param_set.is_a?(Filterrific::ParamSet)
-        raise(ArgumentError, "Invalid Filterrific::ParamSet: #{ filterrific_param_set.inspect }")
+        raise(
+          ArgumentError,
+          "Invalid Filterrific::ParamSet: #{ filterrific_param_set.inspect }"
+        )
       end
 
-      # initialize active record relation
-      ar_rel = if ::ActiveRecord::Relation === self
+      # Initialize ActiveRecord::Relation
+      ar_rel = if ActiveRecord::Relation === self
         # self is already an ActiveRecord::Relation, use as is
         self
-      elsif 3 >= Rails::VERSION::MAJOR
+      elsif Rails::VERSION::MAJOR <= 3
         # Active Record 3: send `:scoped` to class to get an ActiveRecord::Relation
         scoped
       else
@@ -53,8 +60,8 @@ module Filterrific
         all
       end
 
-      # apply filterrific params
-      self.filterrific_filter_names.each do |filter_name|
+      # Apply filterrific params
+      filterrific_available_filters.each do |filter_name|
         filter_param = filterrific_param_set.send(filter_name)
         next if filter_param.blank? # skip blank filter_params
         ar_rel = ar_rel.send(filter_name, filter_param)
@@ -65,29 +72,42 @@ module Filterrific
 
   protected
 
-    def assign_filterrific_filter_names(options)
-      self.filterrific_filter_names = (
-        options['filter_names'] || options['scope_names'] || []
-      ).map { |e| e.to_s }
+    # Defines a :sorted_by scope based on attrs
+    # @param attrs [Hash] with keys as
+    def define_sorted_by_scope(attrs)
+      scope :sorted_by, lambda {}
     end
 
-    def validate_filterrific_filter_names
-      # Raise exception if not filter_names are given
-      raise(ArgumentError, ":filter_names can't be empty")  if filterrific_filter_names.blank?
+    # Assigns available filters.
+    # @param opts [Hash] the complete options hash passed to `filterrific`.
+    #   This method uses the 'available_filters', 'sorted_by', and 'search_query' keys.
+    # @return [void]
+    def assign_filterrific_available_filters(opts)
+      self.filterrific_available_filters = (
+        filterrific_available_filters + (opts['available_filters'] || [])
+      ).map(&:to_s).uniq.sort
+    end
+
+    # Validates presence of at least one available filter.
+    # @return [void]
+    def validate_filterrific_available_filters
+      if filterrific_available_filters.blank?
+        raise(ArgumentError, ":available_filters can't be empty")
+      end
     end
 
-    def assign_filterrific_default_settings(options)
-      self.filterrific_default_settings = (
-        options['default_settings'] || options['defaults'] || {}
+    def assign_filterrific_default_filter_params(opts)
+      self.filterrific_default_filter_params = (
+        opts['default_filter_params'] || {}
       ).stringify_keys
     end
 
-    def validate_filterrific_default_settings
-      # Raise exception if defaults contain keys that are not present in filter_names
+    def validate_filterrific_default_filter_params
+      # Raise exception if defaults contain keys that are not present in available_filters
       if (
-        invalid_defaults = (filterrific_default_settings.keys - filterrific_filter_names)
+        inv_fdfps = filterrific_default_filter_params.keys - filterrific_available_filters
       ).any?
-        raise(ArgumentError, "Invalid default keys: #{ invalid_defaults.inspect }")
+        raise(ArgumentError, "Invalid default filter params: #{ inv_fdfps.inspect }")
       end
     end
 

data/lib/filterrific/engine.rb

@@ -1,4 +1,8 @@
+# -*- coding: utf-8 -*-
+
 require 'filterrific/param_set'
+
+require 'filterrific/action_controller_extension'
 require 'filterrific/action_view_extension'
 require 'filterrific/active_record_extension'
 
@@ -10,14 +14,18 @@ module Filterrific
 
     isolate_namespace Filterrific
 
-    ActiveSupport.on_load :active_record do
-      extend Filterrific::ActiveRecordExtension
+    ActiveSupport.on_load :action_controller do
+      include Filterrific::ActionControllerExtension
     end
 
     ActiveSupport.on_load :action_view do
       include Filterrific::ActionViewExtension
     end
 
+    ActiveSupport.on_load :active_record do
+      extend Filterrific::ActiveRecordExtension
+    end
+
     initializer "filterrific" do |app|
       app.config.assets.precompile += %w(filterrific-spinner.gif)
     end

data/lib/filterrific/param_set.rb

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+
 require 'active_support/all'
 require 'digest/sha1'
 
@@ -6,35 +8,44 @@ module Filterrific
   # FilterParamSet is a container to store FilterParams
   class ParamSet
 
-    attr_accessor :resource_class
+    attr_accessor :model_class
     attr_accessor :select_options
 
-    def initialize(a_resource_class, filterrific_params = {})
-      self.resource_class = a_resource_class
+    # Initializes a new Filterrific::ParamSet. This is the core of Filterrific
+    # where all the action happens.
+    # @param a_model_class [Class] the class you want to filter records of
+    # @param filterrific_params [Hash, optional] the filter params, uses
+    #   model_class' default_settings
+    # @return [Filterrific::ParamSet]
+    def initialize(a_model_class, filterrific_params = {})
+      self.model_class = a_model_class
       @select_options = {}
 
       # Use either passed in filterrific_params or resource class' default_settings.
       # Don't merge the hashes. This causes trouble if an option is set to nil
       # by the user, then it will be overriden by default_settings.
       # You might wonder "what if I want to change only one thing from the defaults?"
-      # Persistence, baby. By the time you submit changes to one dimension, all the others
+      # Persistence, baby. By the time you submit changes to one filter, all the others
       # will be already initialized with the defaults.
-      filterrific_params = resource_class.filterrific_default_settings  if filterrific_params.blank?
+      filterrific_params = model_class.filterrific_default_settings  if filterrific_params.blank?
       filterrific_params.stringify_keys!
       filterrific_params = condition_filterrific_params(filterrific_params)
-      define_attr_accessors_for_each_filter(filterrific_params)
+      define_and_assign_attr_accessors_for_each_filter(filterrific_params)
     end
 
-    # A shortcut to run the ActiveRecord query on resource_class. Use this if
-    # you want to start with the resource_class, and not a special ActiveRecord::Relation.
+    # A shortcut to run the ActiveRecord query on model_class. Use this if
+    # you want to start with the model_class, and not an existing ActiveRecord::Relation.
+    # Allows `@filterrific.find` in controller instead of
+    # `ModelClass.filterrific_find(@filterrific)`
     def find
-      resource_class.filterrific_find(self)
+      model_class.filterrific_find(self)
     end
 
     # Returns Filterrific::ParamSet as hash (used for URL params and serialization)
+    # @return [Hash] with stringified keys
     def to_hash
       {}.tap { |h|
-        resource_class.filterrific_filter_names.each do |filter_name|
+        model_class.filterrific_available_filters.each do |filter_name|
           param_value = self.send(filter_name)
           case
           when param_value.blank?
@@ -49,27 +60,16 @@ module Filterrific
       }
     end
 
+    # Returns params as JSON string.
+    # @return [String]
     def to_json
       to_hash.to_json
     end
 
-    # Returns a signature that is unique to self's params
-    def signature
-      Digest::SHA1.hexdigest(to_hash.to_a.sort.to_s)
-    end
-
-    # Returns true if this Filterrific::ParamSet is not the model's default.
-    # TODO: this doesn't work for procs. I need to evaluate the
-    # filterrific_default_settings before comparing them to to_hash.
-    #
-    # def customized?
-    #   resource_class.filterrific_default_settings != to_hash
-    # end
-
   protected
 
-    # Conditions params
-    # @param[Hash] fp the filterrific params hash
+    # Conditions params: Evaluates Procs and type casts integer values.
+    # @param fp [Hash] the filterrific params hash
     # @return[Hash] the conditioned params hash
     def condition_filterrific_params(fp)
       fp.each do |key, val|
@@ -88,11 +88,11 @@ module Filterrific
       fp
     end
 
-    # Defines attr accessors for each filter name on self and assigns
-    # values based on fp
-    # @param[Hash] fp filterrific_params
-    def define_attr_accessors_for_each_filter(fp)
-      resource_class.filterrific_filter_names.each do |filter_name|
+    # Defines attr accessors for each available_filter on self and assigns
+    # values based on fp.
+    # @param fp [Hash] filterrific_params with stringified keys
+    def define_and_assign_attr_accessors_for_each_filter(fp)
+      model_class.filterrific_available_filters.each do |filter_name|
         self.class.send(:attr_accessor, filter_name)
         v = fp[filter_name]
         self.send("#{ filter_name }=", v)  if v.present?

data/lib/filterrific/version.rb

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+
 module Filterrific
-  VERSION = "1.4.3"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterrific
 version: !ruby/object:Gem::Version
-  version: 1.4.3
+  version: 2.0.0
 platform: ruby
 authors:
 - Jo Hund
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-13 00:00:00.000000000 Z
+date: 2015-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.7.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.7.3
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -70,14 +70,14 @@ dependencies:
   name: wwtd
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.5.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.5.5
 description: Filterrific is a Rails Engine plugin that makes it easy to filter, search,
@@ -101,9 +101,9 @@ files:
 - doc/development_notes/model_api.rb
 - doc/development_notes/view_api.txt
 - doc/meta.md
-- doc/rails_conf_talk.md
 - doc/scratchpad.md
 - lib/filterrific.rb
+- lib/filterrific/action_controller_extension.rb
 - lib/filterrific/action_view_extension.rb
 - lib/filterrific/active_record_extension.rb
 - lib/filterrific/engine.rb
@@ -126,7 +126,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='

data/doc/rails_conf_talk.md

@@ -1,33 +0,0 @@
-# Filterrific Rails Conf Talk
-
-
-Topics to cover:
-
-* filter and sort ActiveRecord lists end to end with lots of code
-* AR scope patterns
-* advanced use cases
-    * export to CSV/XLS
-    * saved searches
-    * full text search
-    * multiple form inputs for single scope
-    * checkbox arrays (collection_check_boxes)
-* filter persistence strategies
-    * session
-    * none (query param)
-    * database (saved searches)
-
-Target audience:
-
-* intermediate
-
-
-Title ideas:
-
-* Tame/awesomify your ActiveRecord lists with Filterrific
-* Dive deep into ActiveRecord scopes, and learn about Filterrific
-* Slice and dice your data in many ways with AR scopes and Filterrific
-
-Other talk ideas (possibly lightning talks?):
-
-* How to safely mutate objects in Rails
-* Service objects, DCI, processors: all dependencies go in one direction