meta_search 0.3.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Ernie Miller
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,101 @@
+= MetaSearch
+
+Extensible searching for your form_for enjoyment.
+
+== Getting Started
+
+Add a line to your Gemfile:
+
+  gem "meta_search"
+
+In your controller:
+
+  def index
+    @search = Article.search(params[:search])
+    @articles = @search.all
+  end
+
+In your view:
+
+  <% form_for :search, @search, :html => {:method => :get} do |f| %>
+    <%= f.label :title_contains %>
+    <%= f.text_field :title_contains %><br />
+    <%= f.label :comments_created_at_greater_than, 'With comments after' %>
+    <%= f.datetime_select :comments_created_at_greater_than, :include_blank => true %><br />
+    <!-- etc... -->
+    <%= f.submit %>
+  <% end %>
+  
+The default Where types are listed at MetaSearch::Where. Options for the search method are documented at MetaSearch::Searches::Base.
+
+== Advanced usage
+
+=== Adding a new Where
+
+If none of the built-in search criteria work for you, you can add a new Where (or 5). To do so,
+create an initializer (<tt>/config/initializers/meta_search.rb</tt>, for instance) and add lines
+like:
+
+  MetaSearch::Where.add :between, :btw, {:condition => 'BETWEEN', :substitutions => '? AND ?'}
+
+See MetaSearch::Where for info on the supported options.
+
+=== multiparameter_field
+
+The example Where above adds support for a "between" search, which requires an array with
+two parameters. These can be passed using Rails multiparameter attributes. To make life easier,
+MetaSearch adds a helper for this:
+
+  <%= f.multiparameter_field :moderations_value_between,
+      {:field_type => :text_field}, {:field_type => :text_field}, :size => 5 %>
+
+<tt>multiparameter_field</tt> works pretty much like the other FormBuilder helpers, but it
+lets you sandwich a list of fields, each in hash format, between the attribute and the usual
+options hash. See MetaSearch::Helpers::FormBuilder for more info.
+
+=== check_boxes and collection_check_boxes
+
+If you need to get an array into your where, and you don't care about parameter order,
+you might choose to use a select or collection_select with multiple selection enabled,
+but everyone hates multiple selection boxes. MetaSearch adds a couple of additional
+helpers, +check_boxes+ and +collection_check_boxes+ to handle multiple selections in a
+more visually appealing manner. It can be called with or without a block, so something
+like this is possible:
+
+  <table>
+    <th colspan="2">How many heads?</th>
+    <% f.check_boxes :number_of_heads_in,
+       [['One', 1], ['Two', 2], ['Three', 3]], :class => 'checkboxy' do |c| %>
+       <tr>
+         <td><%= c[:check_box] %></td>
+         <td><%= c[:label] %></td>
+       </tr>
+    <% end %>
+  </table>
+
+Again, full documentation is in MetaSearch::Helpers::FormBuilder.
+
+=== Excluding attributes and associations
+
+If you'd like to prevent certain associations or attributes from being searchable, you can control
+this inside your models:
+
+  class Article < ActiveRecord::Base
+    metasearch_exclude_attr :some_private_data, :another_private_column
+    metasearch_exclude_assoc :an_association_that_should_not_be_searched, :and_another
+  end
+
+You get the idea. Excluded attributes on a model will be honored across associations, so
+if an Article <tt>has_many :comments</tt> and the Comment model looks something like this:
+
+  Comment < ActiveRecord::Base
+    validates_presence_of :user_id, :body
+    metasearch_exclude_attr :user_id
+  end
+
+Then your call to <tt>Article.search</tt> will allow <tt>:comments_body_contains</tt>
+but not <tt>:comments_user_id_equals</tt> to be passed.
+
+== Copyright
+
+Copyright (c) 2010 {Ernie Miller}[http://metautonomo.us]. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "meta_search"
+    gem.summary = %Q{ActiveRecord 3 object-based searching.}
+    gem.description = %Q{Adds a search method to your ActiveRecord models which returns an object to be used in form_for while constructing a search. Works with Rails 3 only.}
+    gem.email = "ernie@metautonomo.us"
+    gem.homepage = "http://metautonomo.us"
+    gem.authors = ["Ernie Miller"]
+    gem.add_development_dependency "activerecord", ">= 3.0.0.beta"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "meta_search #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/meta_search/builder.rb

@@ -0,0 +1,247 @@
+require 'meta_search/model_compatibility'
+require 'meta_search/exceptions'
+require 'meta_search/where'
+require 'meta_search/utility'
+
+module MetaSearch
+  # Builder is the workhorse of MetaSearch -- it is the class that handles dynamically generating
+  # methods based on a supplied model, and is what gets instantiated when you call your model's search
+  # method. Builder doesn't generate any methods until they're needed, using method_missing to compare
+  # requested method names against your model's attributes, associations, and the configured Where
+  # list.
+  #
+  # === Attributes
+  #
+  # * +base+ - The base model that Builder wraps.
+  # * +search_attributes+ - Attributes that have been assigned (search terms)
+  # * +relation+ - The ActiveRecord::Relation representing the current search.
+  # * +join_dependency+ - The JoinDependency object representing current association join
+  #   dependencies. It's used internally to avoid joining association tables more than
+  #   once when constructing search queries.
+  class Builder
+    include ModelCompatibility
+    include Utility
+    
+    attr_reader :base, :search_attributes, :relation, :join_dependency
+    delegate *RELATION_METHODS, :to => :relation
+
+    # Initialize a new Builder. Requires a base model to wrap, and supports a couple of options
+    # for how it will expose this model and its associations to your controllers/views.
+    def initialize(base, opts = {})
+      @base = base
+      @opts = opts
+      @associations = {}
+      @join_dependency = ActiveRecord::Associations::ClassMethods::JoinDependency.new(@base, [], nil)
+      @search_attributes = {}
+      @relation = @base.scoped
+    end
+    
+    # Return the column info for the given model attribute (if not excluded as outlined above)
+    def column(attr)
+      @base.columns_hash[attr.to_s] if self.includes_attribute?(attr)
+    end
+    
+    # Return the association reflection for the named association (if not excluded as outlined
+    # above)
+    def association(association)
+       if self.includes_association?(association)
+        @associations[association.to_sym] ||= @base.reflect_on_association(association.to_sym)
+      end
+    end
+    
+    # Return the column info for given association and column (if the association is not
+    # excluded from search)
+    def association_column(association, attr)
+      if self.includes_association?(association)
+        assoc = self.association(association)
+        assoc.klass.columns_hash[attr.to_s] unless assoc.klass._metasearch_exclude_attributes.include?(attr.to_s)
+      end
+    end
+    
+    def included_attributes
+      @included_attributes ||= @base.column_names - @base._metasearch_exclude_attributes
+    end
+    
+    def includes_attribute?(attr)
+      self.included_attributes.include?(attr.to_s)
+    end
+    
+    def included_associations
+      @included_associations ||= @base.reflect_on_all_associations.map {|a| a.name.to_s} - @base._metasearch_exclude_associations
+    end
+    
+    def includes_association?(assoc)
+      self.included_associations.include?(assoc.to_s)
+    end
+    
+    # Build the search with the given search options. Options are in the form of a hash
+    # with keys matching the names creted by the Builder's "wheres" as outlined in
+    # MetaSearch::Where
+    def build(opts)
+      opts ||= {}
+      @relation = @base.scoped
+      opts.stringify_keys!
+      opts = collapse_multiparameter_options(opts)
+      assign_attributes(opts)
+      self
+    end
+    
+    private
+    
+    def method_missing(method_id, *args, &block)
+      if match = method_id.to_s.match(/^(.*)\(([0-9]+).*\)$/)
+        method_name, index = match.captures
+        vals = self.send(method_name)
+        vals.is_a?(Array) ? vals[index.to_i - 1] : nil
+      elsif match = matches_attribute_method(method_id)
+        condition, attribute, association = match.captures.reverse
+        build_method(association, attribute, condition)
+        self.send(preferred_method_name(method_id), *args)
+      elsif match = matches_where_method(method_id)
+        condition = match.captures.first
+        build_where_method(condition, Where.new(condition))
+        self.send(method_id, *args)
+      else
+        super
+      end
+    end
+    
+    def build_method(association, attribute, suffix)
+      if association.blank?
+        build_attribute_method(attribute, suffix)
+      else
+        build_association_method(association, attribute, suffix)
+      end
+    end
+    
+    def build_association_method(association, attribute, type)
+      metaclass.instance_eval do        
+        define_method("#{association}_#{attribute}_#{type}") do
+          search_attributes["#{association}_#{attribute}_#{type}"]
+        end
+      
+        define_method("#{association}_#{attribute}_#{type}=") do |val|
+          search_attributes["#{association}_#{attribute}_#{type}"] = cast_attributes(association_type_for(association, attribute), val)
+          where = Where.new(type)
+          if where.valid_substitutions?(search_attributes["#{association}_#{attribute}_#{type}"])
+            join = build_or_find_association(association)
+            self.send("add_#{type}_where", join.aliased_table_name, attribute, search_attributes["#{association}_#{attribute}_#{type}"])
+          end
+        end
+      end
+    end
+    
+    def build_attribute_method(attribute, type)
+      metaclass.instance_eval do
+        define_method("#{attribute}_#{type}") do
+          search_attributes["#{attribute}_#{type}"]
+        end
+      
+        define_method("#{attribute}_#{type}=") do |val|
+          search_attributes["#{attribute}_#{type}"] = cast_attributes(type_for(attribute), val)
+          where = Where.new(type)
+          if where.valid_substitutions?(search_attributes["#{attribute}_#{type}"])
+            self.send("add_#{type}_where", @base.table_name, attribute, search_attributes["#{attribute}_#{type}"])
+          end
+        end
+      end
+    end
+    
+    def build_where_method(condition, where)
+      metaclass.instance_eval do
+        define_method("add_#{condition}_where") do |table, attribute, *args|
+          args.flatten! unless where.keep_arrays?
+          @relation = @relation.where(
+            "#{quote_table_name table}.#{quote_column_name attribute} " + 
+            "#{where.condition} #{where.substitutions}", *format_params(where.formatter, *args)
+          )
+        end
+      end
+    end
+    
+    def format_params(formatter, *params)
+      par = params.map {|p| formatter.call(p)}
+    end
+    
+    def build_or_find_association(association)
+      found_association = @join_dependency.join_associations.detect do |assoc|
+        assoc.reflection.name == association.to_sym
+      end
+      unless found_association
+        @relation = @relation.joins(association.to_sym)
+        @join_dependency.send(:build, association.to_sym, @join_dependency.join_base)
+        found_association = @join_dependency.join_associations.last
+      end
+      found_association
+    end
+    
+    def matches_attribute_method(method_id)
+      method_name = preferred_method_name(method_id)
+      where = Where.new(method_id) rescue nil
+      return nil unless method_name && where
+      match = method_name.match("^(.*)_(#{where.name})=?$")
+      attribute, condition = match.captures
+      if where.types.include?(type_for(attribute))
+        return match
+      elsif match = matches_association(method_name, attribute, condition)
+        association, attribute = match.captures
+        return match if where.types.include?(association_type_for(association, attribute))
+      end
+      nil
+    end
+    
+    def preferred_method_name(method_id)
+      method_name = method_id.to_s
+      where = Where.new(method_name) rescue nil
+      return nil unless where
+      where.aliases.each do |a|
+        break if method_name.sub!(/#{a}(=?)$/, "#{where.name}\\1")
+      end
+      method_name
+    end
+    
+    def matches_association(method_id, attribute, condition)
+      self.included_associations.each do |association|
+        test_attribute = attribute.dup
+        if test_attribute.gsub!(/^#{association}_/, '') &&
+          match = method_id.to_s.match("^(#{association})_(#{test_attribute})_(#{condition})=?$")
+          return match
+        end
+      end
+      nil
+    end
+    
+    def matches_where_method(method_id)
+      if match = method_id.to_s.match(/^add_(.*)_where$/)
+        condition = match.captures.first
+        Where.get(condition) ? match : nil
+      end
+    end
+    
+    def assign_attributes(opts)
+      opts.each_pair do |k, v|
+        self.send("#{k}=", v)
+      end
+    end
+
+    def type_for(attribute)
+      column = self.column(attribute)
+      column.type if column
+    end
+    
+    def class_for(attribute)
+      column = self.column(attribute)
+      column.klass if column
+    end
+    
+    def association_type_for(association, attribute)
+      column = self.association_column(association, attribute)
+      column.type if column
+    end
+    
+    def association_class_for(association, attribute)
+      column = self.association_column(association, attribute)
+      column.klass if column
+    end
+  end
+end

data/lib/meta_search/exceptions.rb

@@ -0,0 +1,3 @@
+module MetaSearch
+  class TypeCastError < StandardError; end
+end

data/lib/meta_search/helpers/action_view.rb

@@ -0,0 +1,168 @@
+require 'action_view'
+require 'action_dispatch'
+
+module ActionDispatch::Http::FilterParameters #:nodoc:
+  protected
+  # Temp fix for Rails 3 beta buggy parameter filtering on arrays 
+  def process_parameter_filter(original_params) #:nodoc:
+    return original_params.dup unless filtering_parameters?
+
+    filtered_params = {}
+    regexps, blocks = compile_parameter_filter
+
+    original_params.each do |key, value|
+      if regexps.find { |r| key =~ r }
+        value = '[FILTERED]'
+      elsif value.is_a?(Hash)
+        value = process_parameter_filter(value)
+      elsif value.is_a?(Array)
+        value = value.map { |v| v.is_a?(Hash) ? process_parameter_filter(v) : v }
+      elsif blocks.present?
+        key = key.dup
+        value = value.dup if value.duplicable?
+        blocks.each { |b| b.call(key, value) }
+      end
+
+      filtered_params[key] = value
+    end
+
+    filtered_params
+  end
+end
+
+module MetaSearch::Helpers
+  module FormBuilder
+    def self.enable! #:nodoc:
+      ::ActionView::Helpers::FormBuilder.class_eval do
+        include FormBuilder
+        self.field_helpers += ['multiparameter_field', 'check_boxes', 'collection_check_boxes']
+      end
+    end
+    
+    # Like other form_for field methods (text_field, hidden_field, password_field) etc,
+    # but takes a list of hashes between the +method+ parameter and the trailing option hash,
+    # if any, to specify a number of fields to create in multiparameter fashion.
+    #
+    # Each hash *must* contain a :field_type option, which specifies a form_for method, and
+    # _may_ contain an optional :type_cast option, with one of the typical multiparameter
+    # type cast characters. Any remaining options will be merged with the defaults specified
+    # in the trailing option hash and passed along when creating that field.
+    #
+    # For example...
+    #
+    #   <%= f.multiparameter_field :moderations_value_between,
+    #       {:field_type => :text_field, :class => 'first'},
+    #       {:field_type => :text_field, :type_cast => 'i'},
+    #       :size => 5 %>
+    #
+    # ...will create the following HTML:
+    #
+    #   <input class="first" id="search_moderations_value_between(1)"
+    #    name="search[moderations_value_between(1)]" size="5" type="text" />
+    #
+    #   <input id="search_moderations_value_between(2i)"
+    #    name="search[moderations_value_between(2i)]" size="5" type="text" />
+    #
+    # As with any multiparameter input fields, these will be concatenated into an
+    # array and passed to the attribute named by the first parameter for assignment.
+    def multiparameter_field(method, *args)
+      defaults = has_multiparameter_defaults?(args) ? args.pop : {}
+      raise ArgumentError, "No multiparameter fields specified" if args.blank?
+      html = ''.html_safe
+      args.each_with_index do |field, index|
+        type = field.delete(:field_type) || raise(ArgumentError, "No :field_type specified.")
+        cast = field.delete(:type_cast) || ''
+        opts = defaults.merge(field)
+        html.safe_concat(
+          @template.send(
+            type.to_s,
+            @object_name,
+            (method.to_s + "(#{index + 1}#{cast})"),
+            objectify_options(opts))
+          )
+      end
+      html
+    end
+    
+    # Behaves almost exactly like the select method, but instead of generating a select tag,
+    # generates checkboxes. Since these checkboxes are just a checkbox and label with no
+    # additional formatting by default, this method can also take a block parameter.
+    #
+    # *Parameters:*
+    #
+    # * +method+ - The method name on the form_for object
+    # * +choices+ - An array of arrays, the first value in each element is the text for the
+    #   label, and the last is the value for the checkbox
+    # * +options+ - An options hash to be passed through to the checkboxes
+    #
+    # If a block is supplied, rather than just rendering the checkboxes and labels, the block
+    # will receive a hash with two keys, :check_box and :label
+    #
+    # *Examples:*
+    #
+    # Simple usage:
+    #
+    #   <%= f.check_boxes :number_of_heads_in,
+    #       [['One', 1], ['Two', 2], ['Three', 3]], :class => 'checkboxy' %>
+    #
+    # This will result in three checkboxes, with the labels "One", "Two", and "Three", and
+    # corresponding numeric values, which will be sent as an array to the :number_of_heads_in
+    # attribute of the form_for object.
+    #
+    # Additional formatting:
+    #
+    #   <table>
+    #     <th colspan="2">How many heads?</th>
+    #     <% f.check_boxes :number_of_heads_in,
+    #        [['One', 1], ['Two', 2], ['Three', 3]], :class => 'checkboxy' do |c| %>
+    #        <tr>
+    #          <td><%= c[:check_box] %></td>
+    #          <td><%= c[:label] %></td>
+    #        </tr>
+    #     <% end %>
+    #   </table>
+    #
+    # This example will output the checkboxes and labels in a tabular format. You get the idea.
+    def check_boxes(method, choices = [], options = {}, &block)
+      unless choices.first.respond_to?(:first) && choices.first.respond_to?(:last)
+        raise ArgumentError, 'invalid choice array specified'
+      end
+      collection_check_boxes(method, choices, :last, :first, options, &block)
+    end
+    
+    # Just like +check_boxes+, but this time you can pass in a collection, value, and text method,
+    # as with collection_select.
+    #
+    # Example:
+    #
+    #    <%= f.collection_check_boxes :head_sizes_in, HeadSize.all,
+    #        :id, :name, :class => 'head-check' %>
+    def collection_check_boxes(method, collection, value_method, text_method, options = {}, &block)
+      html = ''.html_safe
+      collection.each do |choice|
+        text = choice.send(text_method)
+        value = choice.send(value_method)
+        c = {}
+        c[:check_box] = @template.check_box_tag(
+          "#{@object_name}[#{method}][]",
+          value,
+          [@object.send(method)].flatten.include?(value),
+          options.merge(:id => [@object_name, method.to_s, value.to_s.underscore].join('_'))
+        )
+        c[:label] = @template.label_tag([@object_name, method.to_s, value.to_s.underscore].join('_'),
+                                        text)
+        yield c if block_given?
+        html.safe_concat(c[:check_box] + c[:label])
+      end
+      html
+    end
+    
+    private
+    
+    # If the last element of the arguments to multiparameter_field has no :field_type
+    # key, we assume it's got some defaults to be used in the other hashes.
+    def has_multiparameter_defaults?(args)
+      args.size > 1 && args.last.is_a?(Hash) && !args.last.has_key?(:field_type)
+    end
+  end
+end

data/lib/meta_search/model_compatibility.rb

@@ -0,0 +1,8 @@
+module MetaSearch
+  # Just a little module to mix in so that ActionPack doesn't complain.
+  module ModelCompatibility
+    def new_record?
+      false
+    end
+  end
+end

data/lib/meta_search/railtie.rb

@@ -0,0 +1,21 @@
+require 'meta_search'
+
+module MetaSearch
+  class Railtie < Rails::Railtie #:nodoc:
+    railtie_name :meta_search
+    
+    initializer "meta_search.active_record" do |app|
+      if defined? ::ActiveRecord
+        require 'meta_search/searches/active_record'
+        MetaSearch::Searches::ActiveRecord.enable!
+      end
+    end
+    
+    initializer "meta_search.action_view" do |app|
+      if defined? ::ActionView
+        require 'meta_search/helpers/action_view'
+        MetaSearch::Helpers::FormBuilder.enable!
+      end
+    end
+  end
+end

data/lib/meta_search/searches/active_record.rb

@@ -0,0 +1,19 @@
+require 'meta_search/searches/base'
+require 'active_record'
+
+module MetaSearch::Searches
+  module ActiveRecord
+    include MetaSearch::Searches::Base
+    
+    # Mixes MetaSearch into ActiveRecord::Base.
+    def self.enable!
+      ::ActiveRecord::Base.class_eval do
+        class_attribute :_metasearch_exclude_attributes
+        class_attribute :_metasearch_exclude_associations
+        self._metasearch_exclude_attributes = []
+        self._metasearch_exclude_associations = []
+        extend ActiveRecord
+      end
+    end
+  end
+end