filterrific 0.2.0 → 1.0.0

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 1.0.0
+
+* Support for Rails 3.1
+* new model api
+
 ## 0.1.0, released 2010-08-01
 
 * Replicate functionality of Rails 2.3 version

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Jo Hund
+Copyright (c) 2010-2011 Jo Hund
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/VERSION

@@ -1 +1 @@
-0.2.0
+1.0.0

data/doc/development_notes/api_design.txt

@@ -0,0 +1,140 @@
+Conventions and API for filterrific scopes:
+
+Philosophy:
+
+auto generate simple scopes. Any customization is done by overriding the scope. Give
+lots of examples and annotated code.
+
+List of exposed scopes. On first request, load and cache them so that all meta-code has had a chance
+to run (e.g. to dynamically generate scopes).
+
+Only filters defined in filterrific will be exposed via URL. Other scopes will not be accessible
+
+
+
+CONFIG
+===============================================================================
+
+* persist_in_session
+* default_label_method (for view helper selects, radio buttons, checkboxes), default => :name
+
+
+
+
+
+Examples
+
+
+CVIMS:
+* with_publishing_status: custom, looks at state as well as date
+* search_query
+* sorted_by: extracts direction, applies lower(...) to string columns
+* with_tags IN
+* authored_by belongs_to, { :author_id => [*author_ids] }
+
+
+PTS:
+* has_list_options :defaults => {
+  :publication_date_min => lambda { Date.new(Date.today.year, 1, 1).to_s(:calendar_display_area) },
+  :publication_date_max => lambda { Date.new(Date.today.year + 3, 12, 31).to_s(:calendar_display_area) },
+  :sorted_by => 'publication_date_asc',
+  :with_language => Language.all.map(&:id),
+  :with_programme => Programme.all.map(&:id),
+  :with_publication_status => [1, 2, 5, 7],
+  :with_publication_type => PublicationType.all.map(&:id) - [PublicationType.find_partner.nil_or(:id)],
+  :with_sales_item_status => %w[sales_item non_sales_item],
+  :with_commercial_title_status => %w[commercial_title non_commercial_title]
+}
+* interesting method: condition_publication_date_for_named_scope (allows pseudo procs for dates).
+  helpful because procs cannot be marshalled
+* # have to use :include instead of :joins for :roles. If I use :joins, it does an inner join and
+  # returns duplicates for publications. Same for :with_role_type scope.
+  # roles is a habtm relation with publication.
+  named_scope :with_person, lambda{ |person_ids|
+    {
+      :conditions => ["roles.person_id IN (?)", [*person_ids].map(&:to_i)],
+      :include => :roles
+    }
+  }
+* named_scope :with_commercial_title_status, lambda{ |statuses|
+    v = ['1 = 2'] # never true, used if no checkbox is checked ("0")
+    v << 'publications.service_category_id = 1'  if statuses.include?("commercial_title")
+    v << 'publications.service_category_id != 1'  if statuses.include?("non_commercial_title")
+    { :conditions => v.join(' OR ') }
+  }
+* named_scope :sorted_by, lambda { |sort_option|
+    # every sorting should have a set of secondary sort keys. We append those for each case where applicable.
+    secondary_sort_keys = "publications.publication_date asc, lower(publications.short_title) asc, publications.id asc"
+    direction = (sort_option =~ /desc$/) ? 'desc' : 'asc'
+    case sort_option.to_s
+    when /^extent_/
+      { :order => "publications.extent #{direction}" }
+    when /^language_/
+      { :order => "lower(languages.name) #{direction}, #{secondary_sort_keys}",
+        :joins => :language }
+    when /^PM_/
+      { :order => "lower(publications.project_manager_name) #{direction}, #{secondary_sort_keys}" }
+    when /^programme_/
+      { :order => "lower(programmes.name) #{direction}, #{secondary_sort_keys}",
+        :joins => :programme }
+    else
+      raise(ArgumentError, "Invalid sort option: #{sort_option.inspect}")
+    end
+  }
+
+
+
+TIRO
+* filterrific :defaults => {
+    :sorted_by => 'most_recent',
+    :on_or_after => lambda { Time.zone.now.beginning_of_month.to_s(:date) },
+    :billable => true
+  }
+* scope :billable, lambda{ |yes_or_no|
+    case yes_or_no
+    when "yes", true
+      where('activities.is_billable = ?', true)
+    when "no", false
+      where('activities.is_billable = ?', false)
+    else
+      # no setting, don't return any conditions
+    end
+  }
+* scope :for_person, lambda { |person| where("projects.person_id = ?", person.id).joins(:project) }
+* scope :for_date_range, lambda{ |dates|
+    where('activities.date <= ? AND activities.date >= ?', dates.max, dates.min)
+  }
+* scope :on_or_after, lambda{ |date|
+    d = Date.parse(date) if date.is_a?(String)
+    where('activities.date >= ? ', d)
+  }
+
+
+
+
+CANDO
+* saved searches
+* named_scope :search_query, lambda{ |query|
+    # Matches using LIKE. LIKE is case INsensitive with MySQL (Development),
+    # however it is case sensitive with PostGreSQL (Heroku)
+    # To make it work in both worlds, I force everything to lower case.
+    return {} unless query.is_a?(String)
+    # condition query string, parse into individual keywords
+    terms = query.downcase.split(/\s+/)
+    # replace "*" with "%" for wildcard searches
+    terms = terms.map { |e| e.gsub('*', '%') }
+    {
+      :conditions => [
+        terms.map { |term|
+          "lower(conference_participations._first_name) LIKE ? OR lower(conference_participations._last_name) LIKE ?"
+        }.join(' AND '),
+        *(terms.map { |e| e.downcase } * 2)
+      ]
+    }
+  }
+
+
+
+STRATADOCS
+
+* list starts with self as AR proxy

data/doc/development_notes/controller_api.txt

@@ -0,0 +1,27 @@
+CONTROLLER
+==========
+
+There are two methods you use in a controller:
+* filterrific_init to initialize the Filterrific object. It is stored in the @filterrific ivar. This
+  method first initializes the filter params:
+  params[param_name] || session[session_key] || Model.filterrific_defaults
+  Then it persists the filter_params in the session, using session_key.
+* Model.filterrific_find to populate your ActiveRecord collection based on filterrific params.
+  filterrific_find is a composable ActiveRecord relation. That means you can chain it with other
+  relations like scopes, pagination, etc.
+
+Example controller code:
+
+def index
+  @filterrific = filterrific_init(Publication, options={})
+  Options:
+  * :persist_in_session => true OR "publications_list"  # if true, builds session_key from
+    controller-action
+  * :debug => false  # if true, prints out debug info. This also exists in view helper. Maybe one to
+    logger/STDOUT, the other to view?
+  * :param_prefix => "filterrific"  # the param prefix used to shuttle params between view and controller.
+  
+  @publications = Publication.filterrific_find(@filterrific).paginate....
+  @publications = current_user.publications.filterrific_find(@filterrific).paginate....
+  ...
+end

data/doc/development_notes/model_api.rb

@@ -0,0 +1,485 @@
+filterrific do
+  filter :with_project
+  sort ...
+  search ...
+  config :prefix, 'lala'
+  config.debug = true
+end
+
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# TODO: find out why in PTS publications filter, some hidden fields are set to nil and others to "0".
+# If I change it, filter stops working
+
+
+filterrific do
+
+  # Creates custom scope "filterrific_person". Finds all records that have one of the given values
+  # in :person_id column
+  # Accepts: Person.new, 17, [Person.new, Person.new], [12, 13, 14], [12, 13, Person.new]
+  # scope :filterrific_person, lambda { |persons|
+  #   sanitize: convert all entries to an id (integer), convert to array, do nothing if persons.empty?
+  #   foreign_key: inspect association to get foreign key
+  #   where(:person_id => persons)
+  # }
+  filter :belongs_to => :person
+
+  # Creates custom scope "filterrific_is_active". Finds all records that have one of the given
+  # values for :is_active column
+  # Accepts: "true", true, [true, false], [true, 13, false]
+  # scope :filterrific_is_active, lambda { |values|
+  #   sanitize: convert all entries to column type, convert to array, do nothing if values.empty?
+  #   where(:is_active => values)
+  # }
+  filter :column => :is_active, :default => true
+
+  # Creates scopes for date/datetime columns.
+  # Possible conditions: :after, :before, :on_or_after, :on_or_before
+  # scope :filterrific_created_at_on_or_after, lambda { |datetime|
+  #   datetime = sanitize datetime
+  #   return nil  if datetime.blank
+  #   table_name = get tablename from class
+  #   where(['tablename.created_at >= ?', datetime])
+  # }
+  filter :column => :created_at, :condition => :on_or_after, :default => Proc.new { 2.years.ago.beginning_of_year }
+  filter :column => :last_login_on, :condition => :before
+  
+  # Creates custom scope "filterrific_some_complex_scope". Uses scope :some_complex_scope
+  # scope :filterrific_some_complex_scope, lambda { |*args|
+  #   some_complex_scope(args)
+  # }
+  filter :scope => :some_complex_scope
+  
+  # Available options for filter:
+  #
+  # Options for filter type:
+  # :belongs_to: to filter on a belongs_to association
+  # :column: to filter on a column
+  # :scope: to delegate filtering to a scope that is already defined on the class
+  #
+  # General options:
+  # :default: to set the default, can be static value or Proc.new
+  # :name: to change the name for a given filter. The name will still be prefixed with filterrific_prefix
+  #
+  # Possible conditions for :column filters:
+  # * in: contained in set, IN (This is the default condition)
+  # * comparisons: :after, :before, :on_or_after, :on_or_before, >, <, >=, <=
+  # * equals: exactly one, =
+  # * like: LIKE
+  # * between: BETWEEN a AND b
+  
+  # Creates custom scope named "filterrific_sort"
+  sort( 
+    :sort_keys => [
+      { :key => :newest_first, :label => "Newest first", :sql => "created_at DESC" },
+      { :key => :alphabetically, :label => "Name (a-z)", :sql => "name ASC" },
+    ],
+    :default => :newest_first,
+    :secondary_sorting => "name ASC" # will be appended to every sort as secondary sort key
+  )
+  
+  # Creates custom scope named "filterrific_search"
+  search(
+    :columns => [:name, :email, 'provinces.name'], # default: all string columns
+    :joins => :province,
+    :case_sensitive => false, # adds downcase parts to term_processor and SQL query if false
+    :term_splitter => /\s+/,
+    :wild_card_processor => Proc.new({ |e| "%#{ e }%" }) OR Proc.new({ |e| e.gsub('*', '%') }),
+    :default => "some query",
+    :param_name => "search" # somebody might want to set it to "q"
+  )
+  # Alternative search: delegate to pg_search for fulltext search on Postgres
+
+  # If true, prints auto generated and used scopes, current filterrific params, whether all DB
+  # columns have indices
+  config :debug => true # should there be different log levels? option to set output (log, puts)
+  # Prefix is applied to scopes that are available to filterrific. Note that this is different
+  # from the param_prefix that can be set in the controller config.
+  config :scope_prefix => "filterrific_" # default, somebody might want to shorten or remove prefix
+  
+end
+
+scope :some_complex_scope, lambda { |a_value| ... }
+
+
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+
+filterrific do
+
+  # Creates custom scope "filterrific_person". Finds all records that have one of the given values
+  # in :person_ids column
+  # Q: Could I skip the :assciation => true piece? Filterrific could figure this out automatically
+  filter :person, :association => true # instead of true, could be an association name, e.g. :user
+  filter :association => :person # alternative syntax A
+  association :person # alternative syntax B
+  # Creates custom scope "filterrific_active_only". Finds all records that have one of the given
+  # values for :is_active column
+  filter :active_only, :column => :is_active || :some_scope_name, :default => true
+  filter :column => :is_active, :default => true # alternative syntax A
+  column :is_active, :default => true # alternative syntax B
+  # Creates custom scope "filterrific_created_after". Finds all records that have created_at after
+  # the given DateTime
+  filter :created_after, :column => :created_at, :default => Proc.new { 2.years.ago.beginning_of_year }
+  # Creates custom scope "filterrific_complicated_scope". Delegates to an already existing scope
+  # named :complicated_scope_name
+  # Q: How does it know the params expected by :complicated_scope_name?
+  # A: scope :filterrific_complicated_scope_name, lambda { |*attrs| complicated_scope_name(attrs) }
+  filter :complicated_scope, :use_scope => :complicated_scope_name
+  filter :scope => :complicated_scope_name # alternative syntax A
+  scope :complicated_scope_name # alternative syntax B
+  
+  # Creates custom scope named "filterrific_sort"
+  sort( 
+    :sort_keys => [
+      { :key => :newest_first, :label => "Newest first", :sql => "created_at DESC" },
+      { :key => :alphabetically, :label => "Name (a-z)", :sql => "name ASC" },
+    ],
+    :default => :newest_first,
+    :secondary_sorting => "name ASC" # will be appended to every sort as secondary sort key
+  )
+  
+  # Creates custom scope named "filterrific_search"
+  search(
+    :columns => [:name, :email, 'provinces.name'], # default: all string columns
+    :joins => :province,
+    :case_sensitive => false, # adds downcase parts to term_processor and SQL query if false
+    :term_splitter => /\s+/,
+    :wild_card_processor => Proc.new({ |e| "%#{ e }%" }) OR Proc.new({ |e| e.gsub('*', '%') }),
+    :default => "some query",
+    :param_name => "search" # somebody might want to set it to "q"
+  )
+
+  # If true, prints auto generated and used scopes, current filterrific params, whether all DB
+  # columns have indices
+  config :debug => true # should there be different log levels? option to set output (log, puts)
+  config :param_prefix => "filterrific_" # default, somebody might want to shorten or remove prefix
+  
+  auto generate from association
+  auto generate from column
+  delegate to existing scope
+  sort auto or refer
+  search auto or refer
+  
+end
+
+scope :complicated_scope_name, lambda { |...| }
+
+
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+filterrific do
+
+  filter :publication_date_min,
+    :use_scope => :publication_date_min,
+    :default => lambda { Date.new(Date.today.year, 1, 1).to_s(:calendar_display_area) }
+  # need to handle date pre-processing (condition_publication_date_for_named_scope)
+  filter :publication_date_max,
+    :column => :publication_date,
+    :condition => :on_or_before,
+    :default => lambda { Date.new(Date.today.year + 3, 12, 31).to_s(:calendar_display_area) }
+  filter :group, :belongs_to => true, :default => Language.all.map(&:id)
+  filter :language, :belongs_to => true
+  filter :owner, :belongs_to => true # could find the association automatically. Don't need belongs_to here
+  filter :person, :use_scope => :with_person
+  filter :programme, :belongs_to => true, :default => Programme.all.map(&:id)
+  filter :publication_status, :belongs_to => true, :default => [1, 2, 5, 7]
+  filter :publication_type,
+    :belongs_to => true,
+    :default => PublicationType.all.map(&:id) - [PublicationType.find_partner.nil_or(:id)]
+  filter :role_type, :use_scope => :with_role_type
+  filter :department, :use_scope => :for_department
+  
+  # or just referencing stuff that already is declared in the class
+  belongs_to :group # creates scope 'filterrific_with_group'
+  belongs_to :language, :default => Language.all.map(&:id)
+  belongs_to :owner, :default => Programme.all.map(&:id)
+  belongs_to :programme
+  belongs_to :publication_status, :default => [1, 2, 5, 7], :param_name => :status
+  belongs_to :publication_type, :default => PublicationType.all.map(&:id) - [PublicationType.find_partner.nil_or(:id)]
+  
+  scope :publication_date_min, :default => lambda { Date.new(Date.today.year, 1, 1).to_s(:calendar_display_area) }
+  scope :publication_date_max, :default => lambda { Date.new(Date.today.year + 3, 12, 31).to_s(:calendar_display_area) }
+  scope :with_person
+  scope :with_role_type
+  scope :for_department
+  scope :with_sales_item_status, :default => %w[sales_item non_sales_item],
+  scope :with_commercial_title_status, :default => %w[commercial_title non_commercial_title]
+  
+  column: checks for inclusion
+  
+  flag: the sales item checkboxes in PTS
+  
+  search :columns => [:short_title], :param_name => "search_short_title"
+
+  # Two modes: auto generate or manual. If auto, can generate two directions. Manual will always
+  # generate one direction only.
+  # Distinction: :order-option given? ? :manual : :auto
+  #
+  # common options: :key, :label (default: key.to_s.titleize), :apply_secondary_sorting (default: true)
+  # auto only options: :directions (default: [:asc, :desc]),
+  # manual only options: :order, :joins
+  sort(
+    [
+      { :key => :newest_first, :label => "Newest first", :order => "publications.created_at DESC" },
+      { :key => :alphabetically, :label => "Name (a-z)", :order => "users.name ASC", :joins => :users }
+      # creates sort_options extent_asc and extent_desc. Label is defined here on each sort_key.
+      # Would be cumbersome in view.
+      # Creates sort: order("publications.extent ASC, <secondary sort>"), label: "Extent Asc" and
+      #               order("publications.extent DESC, <secondary sort>"), label: "Extent Desc"
+      { :key => :extent, :directions => [:asc, :desc] }, # [:asc, :desc], :asc, :desc, [:asc]
+      { :key => :id },
+      { :key => :owner_id },
+      { :key => :paf_status_id },
+      { :key => :project_manager_name, :label => "PM" },
+      { :key => :publication_date },
+      { :key => :publication_type },
+      { :key => :sales_item },
+      { :key => :short_title },
+      { :key => :updated_at, :apply_secondary_sorting => false },
+      { :key => :programme_asc, :order => "lower(programmes.name) ASC", :joins => :programme },
+      { :key => :language_asc, :order => "lower(languages.name) ASC", :joins => :language },
+      { :key => :status, :order => "lower(publication_statuses.name) ASC", :joins => :publication_status }
+    ],
+    :default => :newest_first,
+    :param_name => :sort,
+    :case_sensitive => false # this uses the lower() SQL modifier around any string columns for auto generated search options
+    :secondary_sorting => {
+      :order => "publications.publication_date asc, lower(publications.short_title) asc, publications.id asc",
+      :joins => :paf_status
+    }
+  )
+  
+end
+
+
+# have to use :include instead of :joins for :roles. If I use :joins, it does an inner join and
+# returns duplicates for publications. Same for :with_role_type scope.
+# roles is a habtm relation with publication.
+named_scope :with_person, lambda{ |person_ids|
+  {
+    :conditions => ["roles.person_id IN (?)", [*person_ids].map(&:to_i)],
+    :include => :roles
+  }
+}
+named_scope :with_role_type, lambda{ |role_type_ids|
+  {
+    :conditions => ["roles.role_type_id IN (?)", [*role_type_ids].map(&:to_i)],
+    :include => :roles
+  }
+}
+named_scope :for_department, lambda{ |department_ids|
+  phase_boundary_event_types = Department.find(
+    [*department_ids].map(&:to_i)
+  ).map(&:phase_boundary_event_types).flatten
+  { :conditions => ["events.event_type_id IN (?)", phase_boundary_event_types.map(&:id)], :joins => :events }
+}
+named_scope :with_sales_item_status, lambda{ |statuses|
+  v = ['1 = 2'] # never true, used if no checkbox is checked ("0")
+  v << 'publications.sales_item = 1'  if statuses.include?("sales_item")
+  v << 'publications.sales_item != 1'  if statuses.include?("non_sales_item")
+  { :conditions => v.join(' OR ') }
+}
+named_scope :with_commercial_title_status, lambda{ |statuses|
+  v = ['1 = 2'] # never true, used if no checkbox is checked ("0")
+  v << 'publications.service_category_id = 1'  if statuses.include?("commercial_title")
+  v << 'publications.service_category_id != 1'  if statuses.include?("non_commercial_title")
+  { :conditions => v.join(' OR ') }
+}
+
+
+
+
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+
+
+
+
+
+
+
+
+
+
+
+
+# Defines a filter available to Filterrific
+#
+# Filters are used to retrieve a subset of all records available, based on a given criterion.
+# Filterrific uses Rails' scopes for this purpose. For each filter specified, Filterrific will
+# create a new scope with the name "filterrific_#{ filter_key }".
+#
+# Filter type option
+#
+# This option tells Filterrific about the kind of filter required. If not given, F tries to figure
+# out the filter type from the filter_key, in the following order:
+#
+# 1) ActiveRecord association on the model with the same name as filter_key
+# 2) Column in the model's table with the same name as filter_key
+# 3) Existing scope on the model with the same name as filter_key
+#
+# Accepts:
+# 
+# * :association(better belongs_to???) - this filter acts on an ActiveRecord association, typically a belongs_to.
+#   Expects: true (F uses the filter_key as association name) or the name of the association as
+#   Symbol or String.
+# * :column - this filter acts on a column on this model's table. Filterrific looks at the column
+#   type to determine what kind of scope is required. See below for column_type specific options.
+#   Expects: true (F uses the filter_key as column_name) or the name of the column as Symbol or String.
+# * :use_scope - accepts Symbod/String to delegate to an existing scope that is already defined on the
+#   model. Alternatively accepts a Proc to define a scope within filterrific. Use the same syntax
+#   as for Rails scopes.
+#   Expects: true (F uses the filter_key as scope_name) or the name of the scope as Symbol or String.
+# 
+# General options
+#
+# These options are applicable to all filter types
+#
+# * :default - the default value for this filter. Used on first call and after reset_filterrific.
+#   Set this on any filter that has a default setting.
+add param name?
+#
+# SQL Options
+#
+# These options are applicable for filters that generate SQL
+#
+# * :joins => tables to join
+# * :includes => tables to include
+#
+# Date filter options
+#
+# These options are applicable to a filter of type :column where the column is of type date.
+# 
+# * :condition - Expects one of :before, :after, :between, :on_or_after, :on_or_before, :at_or_after, :at_or_before
+# 
+# @param [Symbol, String] filter_key the key to be used for this filter
+# @param [Hash] opts the options to specify this filter
+# @return ?
+#
+filter(filter_key, filter_type, opts = {})
+end
+
+
+# Defines sorting for Filterrific
+#
+# Sort is a special type of filter. It is used to allow a user to choose the sorting of a collection.
+#
+# Uses sort_key as internal identifier and also as name for the form param. Creates a scope named
+# "filterrific_#{ sort_key }".
+#
+# Options if using Filterrific internal sort
+# 
+# * :sort_keys - A hash for each sort key with the following options:
+# ** :key - internal name for this sort key. If no :sql given, sorts by column with this name
+# ** :label - label for this sort key, used in views. ?? Shouldn't this be in view helpers?'
+# ** :sql - a SQL fragment used as is to specify sorting
+# ** :joins - joins to be performed for sorting
+# * :secondary_sorting - sort_key that will be appended to every sort as secondary sort key
+# * :default - the :key of the default sort order
+# * :joins - joins to be added to every sort operation (might be required for secondary sorting)
+#
+# Options if using existing scope for sort
+# 
+# * :scope - the name of an existing scope to be used for sort
+# * :default - the :key of the default sort order
+#
+# @param [Array<Hash>] sort_options the sort options to be offered
+# @param [Hash] opts the options to specify sorting
+# @return ?
+#
+def sort(sort_options, opts = {})
+end
+
+
+# Defines search for Filterrific.
+# Search is a special type of filter. It is used to retrieve records from the database that match
+# a given search string. This is typically not as powerful as an indexed search engine, however
+# it can be sufficient in a large number of use cases and is a lot simpler to set up than an index
+# search server like Solr or Lucene (verify search server list!!!).
+#
+# Uses search_key as internal identifier and also as name for the form param. Creates a scope named
+# "filterrific_#{ search_key }".
+#
+# Options if using Filterrific internal search
+#
+# * :columns => [:name, :email, 'provinces.name'], # default: all string columns
+# * :joins => :province
+# * :case_sensitive => false, (adds downcase parts to term_processor and SQL query if false)
+# * :term_splitter => /\s+/
+# * :wild_card_processor => Proc.new({ |e| "%#{ e }%" }) OR Proc.new({ |e| e.gsub('*', '%') })
+# * :default - the value for the default search string. Default: nil
+#
+# Options if using existing scope for search
+#
+# * :scope => :fancy_search # name of an existing scope to be used for search
+# * :default - the value for the default search string. Default: nil
+#
+# @param [Symbol, String] search_key the key to be used for searching
+# @param [Hash] opts the options to specify searching
+# @return ?
+#
+# * CVIMS Content looks like a good and general solution
+#
+def search(search_key, opts = {})
+end
+
+
+# Configures one or more aspects of Filterrific.
+#
+# Available Config options
+#
+# * :debug => true or output type (log, stdout)
+# * :sql_type => :mysql (or :postgresql), possible oracle? Determines how search is handled (regex
+#   vs. like), and any other differences. Could we use Rails' DB connectors for this?
+#
+# @param [Hash] opts the config options
+# @return ?
+#
+def config(opts = {})
+end
+
+
+
+
+Auto generated scopes for author:
+
+* belongs_to: scope :filterrific_with_author_ids, lambda { |author_ids| where({ :author_id => *[author_ids] }
+* has_many: scope exists?
+* collection
+* attribute [String]
+* attribute [Numeric]
+* attribute [Date, DateTime]
+* attribute [Boolean,TinyInt]
+* attribute [Text]
+* 
+
+Each type uses a kind of Filterrific::Matcher:
+
+* search
+* date_time
+* foreign_key
+
+
+
+MODEL
+=====
+
+filterrific do
+
+  associations do
+    person # creates a scope for filterrific
+    state, :default => [1,2,3,4], :type => :select, :multiple => 4
+  end
+  
+  scopes do
+    active_only, :default => true # refers to already defined scope
+    search, :as => "q" (optional param name override)
+    sorted_by, :default => "created_at_desc"
+  end
+  
+  config :debug => true  # prints auto generated and used scopes, current filterrific params, whether all DB columns have indices
+  config ... can't think of any other config options yet.
+end
+
+scope :search, ...

data/doc/development_notes/view_api.txt

@@ -0,0 +1,49 @@
+All view related aspects of filterrific are handled via the view API:
+
+<%= filterrific_form_for @filterrific do |f| %>
+
+  <%= f.select :author, # look at formtastic for inspiration. It auto generates a bunch of stuff %>
+  Options for select:
+  * multiple => false
+  * allow_blank => true or "-- Any --"
+  * value_method => :id
+  * label_method => %w[name title label]
+  * collection => 
+
+  <%= f.boolean :published %>
+  Renders a checkbox
+
+  <%= f.search %>
+  Renders a text box for searching
+  Options:
+  * JS: event: keydown, delay, min_chars
+  * wildcards here or in model?
+
+  <%= f.date or f.datetime %>
+  Renders a text box for date selection. Integrate with jQuery UI calendar select
+  * date is date only
+  * datetime also adds time
+
+  <%= f.radio %>
+  Renders a radio button to select one of many options
+  Options
+  * label_methods => see select
+  * value_method => :id
+  * collection => 
+
+  <%= f.sort %>
+  Renders a select for choosing sort options
+  Options
+  * collection => 
+
+<% end %>
+
+
+<%= filterrific_info(options) %>
+
+Options:
+* :print_all_available_filters
+* :print_current_filter_params
+
+
+Also have to add JS to observe the form. Use generator for that?

data/doc/documentation.md

@@ -14,8 +14,10 @@
 
 * Scenarios
   * Saved search (persist FilterrificParamSet in DB)
-  * Will paginate integration
+  * Will paginate/kaminari integration
   * Session persistence
+  * Interface for JS client side app to get collections of data via JSON REST
+  * integrate with PG fulltext search (pg_search)
 * Defining Scopes
   * Belongs_to
   * Has_many
@@ -27,6 +29,6 @@
 
 ## Requirements
 
-* Rails3
+* Rails3 (or 3.1?)
 
   

data/doc/ideas.txt

@@ -1,3 +1,43 @@
+20110418: Look at this when building API: https://github.com/ryan-allen/lispy
+
+
+20110414 Related project:
+
+* https://github.com/plataformatec/has_scope
+
+20110221 Promotion:
+
+* railscasts (even ask for review/feedback)
+* railsinside
+* ruby toolbox
+
+
+20110205: figuring out best prefix for namespacing filterrific
+
+balance between shortness and expression:
+
+f
+fc
+ft
+frc
+ftf
+fifc
+flfc
+frfc
+ftfc
+ftrfc
+fltrfc
+filtrfc
+filterrific
+
+20110112: see if I can learn something here:
+http://www.idolhands.com/ruby-on-rails/guides-tips-and-tutorials/add-filters-to-views-using-named-scopes-in-rails
+
+
+20101227: get inspiration from this project: https://github.com/neerajdotname/admin_data
+look especially at their query builder in the heroku demo project (add conditions like Finder search)
+
+
 Glean specific code from these projects:
 
 20100224 CVIMS
@@ -6,28 +46,6 @@ Glean specific code from these projects:
 201001   Quentin-rails-backend
          stratadocs (list starts with self as AR proxy)
 
-MODEL
-=====
-
-filterrific do
-
-  associations do
-    person # creates a scope for filterrific
-    state, :default => [1,2,3,4], :type => :select, :multiple => 4
-  end
-  
-  scopes do
-    active_only, :default => true # refers to already defined scope
-    search, :as => "q" (optional param name override)
-    sorted_by, :default => "created_at_desc"
-  end
-  
-  persist_in_session false # overrides global filterrific settings
-end
-
-scope :search, ...
-
-Only filters defined in filterrific will be exposed via URL. Other scopes will not be accessible
 
 view
 (skip these for now?)
@@ -36,30 +54,8 @@ integrate with formtastic?
 
 
 
-CONTROLLER
-==========
-
-def index
-  @filter_options = init_filterrific(Publication, :publications_list)
-  @publications = Publication.filterrific(@filter_options).paginate....
-  @publications = current_user.publications.filterrific(@filter_options).paginate....
-  ...
-end
-
-def init_filterrific(klass, scope = nil)
-  scope_name ||= klass.to_s.underscore # use resource class name as default scope name
-  filter_options_hash = params[:filter_options]
-  filter_options_hash ||= session[scope_name]  if filterrific.persist_in_session
-  @filter_options = Filterrific.new(Publication, params[:filter_options])
-  session[scope_name] = @filter_options.to_hash   if filterrific.persist_in_session # (store sanitized options). Maybe just define marshal dump? skip to_hash
-end
 
 
-Filterrific CONFIG
-==================
-
-Settings:
-* persist_in_session
 
 
 

data/doc/todo.md

@@ -1,8 +1,21 @@
+To make it work on Rails 3.1:
+
+* follow kaminari gem for recipe
+* implement new model api
+* leave view and controller as is
+* bump version to 1.0.0 (not backwards compatible)
+
+Later:
+* build filterrific-recipes on github wiki
+* update readme
+* update view and controller apis
+
+
 # Implementation Plan for Filterrific
 
 ## Version 0.1.0: Rebuild current Rails2 functionality
 
 ## Add DSL and scope generator
-
+## Write specs (http://avdi.org/devblog/2011/04/07/rspec-is-for-the-literate/ also read comments about be_...!)
 ## Add Filterrific form builder
 

data/filterrific.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
 # DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{filterrific}
-  s.version = "0.2.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jo Hund"]
-  s.date = %q{2010-08-25}
+  s.date = %q{2011-11-09}
   s.description = %q{
       The Rails User Interface solution for filtering your ActiveRecord lists:
 
@@ -23,47 +23,44 @@ Gem::Specification.new do |s|
   s.email = %q{jhund@clearcove.ca}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+    "README.rdoc"
   ]
   s.files = [
-    ".gitignore",
-     "CHANGELOG.md",
-     "LICENSE",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION",
-     "doc/Overview diagram.graffle/QuickLook/Preview.pdf",
-     "doc/Overview diagram.graffle/QuickLook/Thumbnail.tiff",
-     "doc/Overview diagram.graffle/data.plist",
-     "doc/Overview diagram.graffle/image1.tiff",
-     "doc/documentation.md",
-     "doc/ideas.txt",
-     "doc/todo.md",
-     "doc/workflow.md",
-     "filterrific.gemspec",
-     "lib/filterrific.rb",
-     "lib/filterrific/model_mixin.rb",
-     "lib/filterrific/param_set.rb",
-     "lib/filterrific/railtie.rb",
-     "lib/filterrific/view_helpers.rb",
-     "test/helper.rb",
-     "test/test_filterrific.rb"
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "doc/Overview diagram.graffle/QuickLook/Preview.pdf",
+    "doc/Overview diagram.graffle/QuickLook/Thumbnail.tiff",
+    "doc/Overview diagram.graffle/data.plist",
+    "doc/Overview diagram.graffle/image1.tiff",
+    "doc/development_notes/api_design.txt",
+    "doc/development_notes/controller_api.txt",
+    "doc/development_notes/model_api.rb",
+    "doc/development_notes/view_api.txt",
+    "doc/documentation.md",
+    "doc/ideas.txt",
+    "doc/todo.md",
+    "doc/workflow.md",
+    "filterrific.gemspec",
+    "lib/filterrific.rb",
+    "lib/filterrific/model_mixin.rb",
+    "lib/filterrific/param_set.rb",
+    "lib/filterrific/railtie.rb",
+    "lib/filterrific/view_helpers.rb",
+    "test/helper.rb",
+    "test/test_filterrific.rb"
   ]
   s.homepage = %q{http://github.com/jhund/filterrific}
-  s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.5.2}
   s.summary = %q{The Rails User Interface solution for filtering your ActiveRecord lists.}
-  s.test_files = [
-    "test/helper.rb",
-     "test/test_filterrific.rb"
-  ]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
       s.add_development_dependency(%q<yard>, [">= 0"])
     else

data/lib/filterrific/model_mixin.rb

@@ -8,12 +8,17 @@ module Filterrific::ModelMixin
 
     # Adds filterrific behavior to class when called like so:
     # 
-    # filterrific, :defaults => { :sorted_by => "created_at_asc" }
+    # filterrific(
+    #   :defaults => { :sorted_by => "created_at_asc" },
+    #   :scope_names => [:sorted_by, :search_query, :with_state]
+    # )
     #
     def filterrific(options = {})
       # send :include, InstanceMethods
       cattr_accessor :default_filterrific_params
+      cattr_accessor :filterrific_scope_names
       self.default_filterrific_params = (options[:defaults] || {}).stringify_keys
+      self.filterrific_scope_names = (options[:scope_names] || []).stringify_keys
     end
 
     # Returns AR relation based on given filterrific_param_set.
@@ -38,11 +43,6 @@ module Filterrific::ModelMixin
       ar_proxy
     end
 
-    # Returns Array all filter scope names
-    def filterrific_scope_names
-      scopes.map{ |s| s.first.to_s }
-    end
-
   end
 
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: filterrific
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  hash: 23
+  prerelease: 
   segments: 
+  - 1
   - 0
-  - 2
   - 0
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Jo Hund
@@ -14,16 +15,18 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-25 00:00:00 -07:00
+date: 2011-11-09 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: thoughtbot-shoulda
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -33,9 +36,11 @@ dependencies:
   name: yard
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -51,7 +56,6 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 files: 
-- .gitignore
 - CHANGELOG.md
 - LICENSE
 - README.rdoc
@@ -61,6 +65,10 @@ files:
 - doc/Overview diagram.graffle/QuickLook/Thumbnail.tiff
 - doc/Overview diagram.graffle/data.plist
 - doc/Overview diagram.graffle/image1.tiff
+- doc/development_notes/api_design.txt
+- doc/development_notes/controller_api.txt
+- doc/development_notes/model_api.rb
+- doc/development_notes/view_api.txt
 - doc/documentation.md
 - doc/ideas.txt
 - doc/todo.md
@@ -78,31 +86,34 @@ homepage: http://github.com/jhund/filterrific
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
+rdoc_options: []
+
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
 summary: The Rails User Interface solution for filtering your ActiveRecord lists.
-test_files: 
-- test/helper.rb
-- test/test_filterrific.rb
+test_files: []
+

data/.gitignore

@@ -1,17 +0,0 @@
-## MAC OS
-.DS_Store
-
-## PROJECT::GENERAL
-*.gem
-coverage
-rdoc
-pkg
-tmp
-log
-.yardoc
-measurements
-
-## BUNDLER
-.bundle
-Gemfile.local
-Gemfile.lock