filterrific 0.0.0 → 0.1.0

data/doc/documentation.md

@@ -0,0 +1,32 @@
+# Filterrific Documentation
+
+## Word list
+
+* Filterrific - the gem
+* Filterrific::Param - individual element of a *FilterrificParamSet*.
+  Defines how the AR list should be filtered. Managed via instance of *FilterrificParamSet* class.
+* Filterrific::ScopeNames - List of *Scope* names that are available to *Filterrific*.
+* Filterrific::ParamSet - Container for *FilterrificParams*
+* Filterrific::Form - a HTML form used to define *FilterrificParams*
+* Scope - An ActiveRecord scope (formerly known as named_scope)
+
+## Brain dump
+
+* Scenarios
+  * Saved search (persist FilterrificParamSet in DB)
+  * Will paginate integration
+  * Session persistence
+* Defining Scopes
+  * Belongs_to
+  * Has_many
+  * Sorting
+  * Full text search (Postgres, Like, regex, Sphinx?)
+* Filterrific form inputs
+  * checkboxes
+  * multi selects
+
+## Requirements
+
+* Rails3
+
+  

data/{design → doc}/ideas.txt

@@ -99,4 +99,8 @@ Filterrific relies heavily on scopes. Each filter dimension has its own scope. F
 easy to shuttle user settings to your controllers and models for queries, and back to the views.
 
 
+Related projects
+================
+
+* http://github.com/plataformatec/has_scope
 

data/doc/todo.md

@@ -0,0 +1,8 @@
+# Implementation Plan for Filterrific
+
+## Version 0.1.0: Rebuild current Rails2 functionality
+
+## Add DSL and scope generator
+
+## Add Filterrific form builder
+

data/doc/workflow.md

@@ -0,0 +1,17 @@
+# Workflow to Maintain This Gem
+
+1. Update code and commit it.
+2. Bump the version with one of the rake tasks:
+   * `rake version:bump:patch` 1.5.3 -> 1.5.4
+   * `rake version:bump:minor` 1.5.3 -> 1.6.0
+   * `rake version:bump:major` 1.5.3 -> 2.0.0
+   * `rake version:write MAJOR=2 MINOR=3 PATCH=6` 1.5.3 -> 2.3.6
+3. Add entry to CHANGELOG:
+   * h1 for major release
+   * h2 for minor release
+   * h3 for patch release
+4. Release it.
+   * `rake release`
+   * Optionally release it to Rubyforge: `rake rubyforge:release`
+   * Optionally release it to Gemcutter: `rake gemcutter:release`
+5. Rinse and repeat

data/filterrific.gemspec

@@ -0,0 +1,78 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{filterrific}
+  s.version = "0.1.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-01}
+  s.description = %q{
+      The Rails User Interface solution for filtering your ActiveRecord lists:
+
+      * Built from the ground up for Rails3
+      * Build filter forms with ease
+      * Filter ActiveRecord lists using AR scopes
+      * Shuttle filter parameters from view to controller to model in a RESTful way
+      * Auto-generate scopes for AR associations (Planned)
+      * Form builder for filter UI forms (Planned)
+    }
+  s.email = %q{jhund@clearcove.ca}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "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"
+  ]
+  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.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
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end
+

data/lib/filterrific.rb

@@ -0,0 +1,11 @@
+# = The Rails User Interface Solution for Filtering Your ActiveRecord Lists
+#
+module Filterrific
+
+  if defined?(Rails) && Rails::VERSION::MAJOR == 3
+    require 'filterrific/railtie'
+  else
+    raise "Filterrific requires Rails 3"
+  end
+
+end

data/lib/filterrific/model_mixin.rb

@@ -0,0 +1,48 @@
+module Filterrific::ModelMixin
+    
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+  module ClassMethods
+
+    # Adds filterrific behavior to class when called like so:
+    # 
+    # filterrific, :defaults => { :sorted_by => "created_at_asc" }
+    #
+    def filterrific(options = {})
+      # send :include, InstanceMethods
+      cattr_accessor :default_filterrific_params
+      self.default_filterrific_params = (options[:defaults] || {}).stringify_keys
+    end
+
+    # Returns AR relation based on given filterrific_param_set.
+    #
+    # ModelClass.filterrific_find(@filterrific_param_set)
+    #
+    def filterrific_find(filterrific_param_set)
+      unless filterrific_param_set.is_a?(Filterrific::ParamSet)
+        raise(ArgumentError, "Invalid Filterrific::ParamSet: #{ filterrific_param_set.inspect }")
+      end
+
+      # set initial ar_proxy to including class
+      ar_proxy = self
+      
+      # apply filterrific params
+      self.filterrific_scope_names.each do |scope_name|
+        scope_param = filterrific_param_set.send(scope_name)
+        next if scope_param.blank? # skip blank scope_params
+        ar_proxy = ar_proxy.send(scope_name, scope_param)
+      end
+
+      ar_proxy
+    end
+
+    # Returns Array all filter scope names
+    def filterrific_scope_names
+      scopes.map{ |s| s.first.to_s }
+    end
+
+  end
+
+end

data/lib/filterrific/param_set.rb

@@ -0,0 +1,73 @@
+module Filterrific
+
+  # FilterParamSet is a container to store FilterParams for a resource class that is filterrific
+  class ParamSet
+
+    attr_accessor :resource_class
+
+    def initialize(resource_class, filterrific_params = {})
+
+      self.resource_class = resource_class
+
+      # use either passed in options or resource class' default list_options
+      # don't merge them. This causes trouble if an option is set to nil
+      # by the user, then it will be overriden by default list_options
+      # 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
+      # will be already initialized with the defaults.
+      filterrific_params = resource_class.default_filterrific_params if filterrific_params.blank?
+
+      # force all keys to strings
+      filterrific_params.stringify_keys!
+
+      # condition filterrific_params
+      filterrific_params.each do |key, val|
+        case
+        when val.is_a?(Proc)
+          # evaulate Procs
+          filterrific_params[key] = val.call
+        when val.is_a?(Array)
+          # type cast integers
+          filterrific_params[key] = filterrific_params[key].map { |e| e =~ /^\d+$/ ? e.to_i : e }
+        when val =~ /^\d+$/
+          # type cast integers
+          filterrific_params[key] = filterrific_params[key].to_i
+        end
+      end
+
+      # Define attr_accessor for each FilterrificScope
+      # on Filterrific::ParamSet instance and assign values from options
+      resource_class.filterrific_scope_names.each do |scope_name|
+        self.class.send(:attr_accessor, scope_name)
+        v = filterrific_params[scope_name.to_s]
+        self.send("#{ scope_name }=", v)  if v.present?
+      end
+
+    end
+
+    # Returns FilterrificParams as hash (used for URL params and serialization)
+    def to_hash
+      {}.tap { |h|
+        resource_class.filterrific_scope_names.each do |scope_name|
+          param_value = self.send(scope_name)
+          case
+          when param_value.blank?
+            # do nothing
+          when param_value.is_a?(Proc)
+            # evaluate Proc so it can be serialized
+            h[scope_name.to_s] = param_value.call
+          else
+            h[scope_name.to_s] = param_value
+          end
+        end
+      }
+    end
+
+    # Returns true if this Filterrific::ParamSet is not the model's default.
+    def customized?
+      resource_class.default_filterrific_params != to_hash
+    end
+
+  end
+
+end

data/lib/filterrific/railtie.rb

@@ -0,0 +1,25 @@
+require 'filterrific'
+require 'rails'
+
+module Filterrific
+
+  class Railtie < Rails::Railtie
+    
+    initializer "filterrific.model_mixin" do |app|
+      require 'filterrific/model_mixin'
+      ActiveRecord::Base.send(:include, Filterrific::ModelMixin)
+      require 'filterrific/param_set'
+    end
+    
+    initializer "filterrific.view_helpers" do |app|
+      require 'filterrific/view_helpers'
+      ActionView::Base.send(:include, Filterrific::ViewHelpers)
+    end
+    
+    # to_prepare block is executed once in production and before each request in development
+    # config.to_prepare do
+    # end
+
+  end
+  
+end

data/lib/filterrific/view_helpers.rb

@@ -0,0 +1,35 @@
+module Filterrific::ViewHelpers
+
+  # renders javascript to observe filter form
+  def observe_list_options_filter(options = {})
+    # default options
+    options = {
+      :form_id => 'list_options_filter',
+      :method => :get,
+      :live_field_ids => [],
+      :url => url_for(:controller => controller.controller_path, :action => controller.action_name)
+    }.merge(options)
+    # observe the entire form regularly (triggers e.g. when a select option is clicked)
+    # observe_form(
+    #   options[:form_id],
+    #   :function => observer_ajax_javascript(options, 'value'),
+    #   :frequency => 0.5
+    # )
+  end
+
+  def render_list_options_spinner
+    %(<span id="list_options_spinner" class="spinner" style="display:none;"> </span>)
+  end
+
+private
+
+  def observer_ajax_javascript(options, parameters_to_be_submitted)
+    # options = {
+    #   :with => parameters_to_be_submitted,
+    #   :loading => "$('#list_options_spinner').show()",
+    #   :complete => "$('#list_options_spinner').hide()"
+    # }.merge(options)
+    # remote_function(options)
+  end
+
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 0
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jo Hund
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-30 00:00:00 -07:00
+date: 2010-08-01 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,7 +41,7 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id002
-description: Add filter controls to your ActiveRecord lists and persist filter settings via session or DB
+description: "\n      The Rails User Interface solution for filtering your ActiveRecord lists:\n\n      * Built from the ground up for Rails3\n      * Build filter forms with ease\n      * Filter ActiveRecord lists using AR scopes\n      * Shuttle filter parameters from view to controller to model in a RESTful way\n      * Auto-generate scopes for AR associations (Planned)\n      * Form builder for filter UI forms (Planned)\n    "
 email: jhund@clearcove.ca
 executables: []
 
@@ -51,12 +51,26 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 files: 
+- .gitignore
+- CHANGELOG.md
 - LICENSE
 - README.rdoc
 - Rakefile
 - VERSION
-- design/ideas.txt
+- 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
 has_rdoc: true
@@ -88,7 +102,7 @@ rubyforge_project:
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: Add filter controls to your ActiveRecord lists and persist filter settings via session or DB
+summary: The Rails User Interface solution for filtering your ActiveRecord lists.
 test_files: 
 - test/helper.rb
 - test/test_filterrific.rb