meta_search 0.3.0 → 0.5.0

data/lib/meta_search/exceptions.rb

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

data/lib/meta_search/helpers.rb

@@ -0,0 +1,3 @@
+require 'meta_search/helpers/form_builder'
+require 'meta_search/helpers/form_helper'
+require 'meta_search/helpers/url_helper'

data/lib/meta_search/helpers/form_builder.rb

@@ -0,0 +1,152 @@
+require 'action_view'
+require 'action_view/template'
+module MetaSearch
+  Check = Struct.new(:box, :label)
+  
+  module Helpers
+    module FormBuilder
+      extend ActiveSupport::Concern
+      
+      included do
+        self.field_helpers += ['multiparameter_field', 'check_boxes', 'collection_check_boxes']
+      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 <tt>MetaSearch::Check</tt>s. These consist of two attributes, +box+ and +label+,
+      # which are (unsurprisingly) the HTML for the check box and the label. Called without a block,
+      # this method will return an array of check boxes. Called with a block, it will yield each
+      # check box to your template.
+      #
+      # *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
+      #
+      # *Examples:*
+      #
+      # <b>Simple formatting:</b>
+      #
+      #   <h4>How many heads?</h4>
+      #   <ul>
+      #     <% f.check_boxes :number_of_heads_in,
+      #        [['One', 1], ['Two', 2], ['Three', 3]], :class => 'checkboxy' do |check| %>
+      #        <li>
+      #          <%= check.box %>
+      #          <%= check.label %>
+      #        </li>
+      #     <% end %>
+      #   </ul>
+      #
+      # This example will output the checkboxes and labels in an unordered list format.
+      #
+      # <b>Grouping:</b>
+      #
+      # Chain <tt>in_groups_of(<num>, false)</tt> on check_boxes like so:
+      #   <h4>How many heads?</h4>
+      #   <p>
+      #     <% f.check_boxes(:number_of_heads_in,
+      #        [['One', 1], ['Two', 2], ['Three', 3]],
+      #        :class => 'checkboxy').in_groups_of(2, false) do |checks| %>
+      #       <% checks.each do |check| %>
+      #         <%= check.box %>
+      #         <%= check.label %>
+      #       <% end %>
+      #       <br />
+      #     <% end %>
+      #   </p>
+      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 => 'headcheck' do |check| %>
+      #     <%= check.box %> <%= check.label %>
+      #   <% end %>
+      def collection_check_boxes(method, collection, value_method, text_method, options = {}, &block)
+        check_boxes = []
+        collection.each do |choice|
+          text = choice.send(text_method)
+          value = choice.send(value_method)
+          check = MetaSearch::Check.new
+          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('_'))
+          )
+          check.label = @template.label_tag([@object_name, method.to_s, value.to_s.underscore].join('_'),
+                                        text)
+          if block_given?
+            yield check
+          else
+            check_boxes << check
+          end
+        end
+        check_boxes unless block_given?
+      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
+end

data/lib/meta_search/helpers/form_helper.rb

@@ -0,0 +1,20 @@
+module MetaSearch
+  module Helpers
+    module FormHelper
+      def apply_form_for_options!(object_or_array, options)
+        if object_or_array.is_a?(Array) && object_or_array.first.is_a?(MetaSearch::Builder)
+          builder = object_or_array.first
+          html_options = {
+            :class  => options[:as] ? "#{options[:as]}_search" : "#{builder.base.to_s.underscore}_search",
+            :id => options[:as] ? "#{options[:as]}_search" : "#{builder.base.to_s.underscore}_search",
+            :method => :get }
+          options[:html] ||= {}
+          options[:html].reverse_merge!(html_options)
+          options[:url] ||= polymorphic_path(builder.base)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/meta_search/helpers/url_helper.rb

@@ -0,0 +1,39 @@
+module MetaSearch
+  module Helpers
+    module UrlHelper
+      
+      def sort_link(builder, attribute, *args)
+        raise ArgumentError, "Need a MetaSearch::Builder search object as first param!" unless builder.is_a?(MetaSearch::Builder)
+        attr_name = attribute.to_s
+        name = (args.size > 0 && !args.first.is_a?(Hash)) ? args.shift.to_s : attr_name.humanize
+        prev_attr, prev_order = builder.search_attributes['meta_sort'].to_s.split('.')
+        current_order = prev_attr == attr_name ? prev_order : nil
+        new_order = current_order == 'asc' ? 'desc' : 'asc'
+        options = args.first.is_a?(Hash) ? args.shift : {}
+        html_options = args.first.is_a?(Hash) ? args.shift : {}
+        css = ['sort_link', current_order].compact.join(' ')
+        html_options[:class] = [css, html_options[:class]].compact.join(' ')
+        options.merge!(
+          'search' => builder.search_attributes.merge(
+            'meta_sort' => [attr_name, new_order].join('.')
+          )
+        )
+        link_to [ERB::Util.h(name), order_indicator_for(current_order)].compact.join(' ').html_safe,
+                url_for(options),
+                html_options
+      end
+      
+      private
+      
+      def order_indicator_for(order)
+        if order == 'asc'
+          '▲'
+        elsif order == 'desc'
+          '▼'
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/meta_search/method.rb

@@ -0,0 +1,129 @@
+require 'meta_search/utility'
+
+module MetaSearch
+  # MetaSearch can be given access to any class method on your model to extend its search capabilities.
+  # The only rule is that the method must return an ActiveRecord::Relation so that MetaSearch can
+  # continue to extend the search with other attributes. Conveniently, scopes (formerly "named scopes")
+  # do this already.
+  #
+  # Consider the following model:
+  #
+  #   class Company < ActiveRecord::Base
+  #     has_many :slackers, :class_name => "Developer", :conditions => {:slacker => true}
+  #     scope :backwards_name, lambda {|name| where(:name => name.reverse)}
+  #     scope :with_slackers_by_name_and_salary_range,
+  #       lambda {|name, low, high|
+  #         joins(:slackers).where(:developers => {:name => name, :salary => low..high})
+  #       }
+  #   end
+  #
+  # To allow MetaSearch access to a model method, including a named scope, just use
+  # <tt>search_methods</tt> in the model:
+  #
+  #   search_methods :backwards_name
+  #
+  # This will allow you to add a text field named :backwards_name to your search form, and
+  # it will behave as you might expect.
+  #
+  # In the case of the second scope, we have multiple parameters to pass in, of different
+  # types. We can pass the following to <tt>search_methods</tt>:
+  #
+  #   search_methods :with_slackers_by_name_and_salary_range,
+  #     :splat_param => true, :type => [:string, :integer, :integer]
+  #
+  # MetaSearch needs us to tell it that we don't want to keep the array supplied to it as-is, but
+  # "splat" it when passing it to the model method. And in this case, ActiveRecord would have been
+  # smart enough to handle the typecasting for us, but I wanted to demonstrate how we can tell
+  # MetaSearch that a given parameter is of a specific database "column type." This is just a hint
+  # MetaSearch uses in the same way it does when casting "Where" params based on the DB column
+  # being searched. It's also important so that things like dates get handled properly by FormBuilder.
+  #
+  # _NOTE_: If you do supply an array, rather than a single type value, to <tt>:type</tt>, MetaSearch
+  # will enforce that any array supplied for input by your forms has the correct number of elements
+  # for your eventual method.
+  #
+  # Besides <tt>:splat_param</tt> and <tt>:type</tt>, search_methods accept the same <tt>:formatter</tt>
+  # and <tt>:validator</tt> options that you would use when adding a new MetaSearch::Where:
+  #
+  # <tt>formatter</tt> is the Proc that will do any formatting to the variable passed to your method.
+  # The default proc is <tt>{|param| param}</tt>, which doesn't really do anything. If you pass a
+  # string, it will be +eval+ed in the context of this Proc.
+  #
+  # If your method will do a LIKE search against its parameter, you might want to pass:
+  #
+  #   :formatter => '"%#{param}%"'
+  #
+  # Be sure to single-quote the string, so that variables aren't interpolated until later. If in doubt,
+  # just use a Proc, like so:
+  #
+  #   :formatter => Proc.new {|param| "%#{param}%"}
+  #
+  # <tt>validator</tt> is the Proc that will be used to check whether a parameter supplied to the
+  # method is valid. If it is not valid, it won't be used in the query. The default is
+  # <tt>{|param| !param.blank?}</tt>, so that empty parameters aren't added to the search, but you
+  # can get more complex if you desire. Validations are run after typecasting, so you can check
+  # the class of your parameters, for instance.
+  class Method
+    include Utility
+    
+    attr_reader :name, :formatter, :validator, :type
+    
+    def initialize(name, opts ={})
+      raise ArgumentError, "Name parameter required" if name.blank?
+      @name = name
+      @type = opts[:type] || :string
+      @splat_param = opts[:splat_param] || false
+      @formatter = opts[:formatter] || Proc.new {|param| param}
+      if @formatter.is_a?(String)
+        formatter = @formatter
+        @formatter = Proc.new {|param| eval formatter}
+      end
+      unless @formatter.respond_to?(:call)
+        raise ArgumentError, "Invalid formatter for #{name}, should be a Proc or String."
+      end
+      @validator = opts[:validator] || Proc.new {|param| !param.blank?}
+      unless @validator.respond_to?(:call)
+        raise ArgumentError, "Invalid validator for #{name}, should be a Proc."
+      end
+    end
+    
+    # Cast the parameter to the type specified in the Method's <tt>type</tt>
+    def cast_param(param)
+      if type.is_a?(Array)
+        unless param.is_a?(Array) && param.size == type.size
+          num_params = param.is_a?(Array) ? param.size : 1
+          raise ArgumentError, "Parameters supplied to #{name} could not be type cast -- #{num_params} values supplied, #{type.size} expected"
+        end
+        type.each_with_index do |t, i|
+          param[i] = cast_attributes(t, param[i])
+        end
+        param
+      else
+        cast_attributes(type, param)
+      end
+    end
+    
+    # Evaluate the method in the context of the supplied relation and parameter
+    def eval(relation, param)
+      if splat_param?
+        relation.send(name, *format_param(param))
+      else
+        relation.send(name, format_param(param))
+      end
+    end
+    
+    def splat_param?
+      !!@splat_param
+    end
+    
+    # Format a parameter for searching using the Method's defined formatter.
+    def format_param(param)
+      formatter.call(param)
+    end
+    
+    # Validate the parameter for use in a search using the Method's defined validator.
+    def validate(param)
+      validator.call(param)
+    end
+  end
+end

data/lib/meta_search/model_compatibility.rb

@@ -1,8 +1,42 @@
 module MetaSearch
   # Just a little module to mix in so that ActionPack doesn't complain.
   module ModelCompatibility
-    def new_record?
-      false
+    def self.included(base) 
+      base.extend ClassMethods
     end
+    
+    # Force default "Update search" text
+    def persisted?
+      true
+    end
+    
+    def to_key
+      nil
+    end
+    
+    def to_param
+      nil
+    end
+    
+    class Name < String
+      attr_reader :singular, :plural, :element, :collection, :partial_path, :human
+      alias_method :cache_key, :collection
+
+      def initialize
+        super("Search")
+        @singular = "search".freeze
+        @plural = "searches".freeze
+        @element = "search".freeze
+        @human = "Search".freeze
+        @collection = "meta_search/searches".freeze
+        @partial_path = "#{@collection}/#{@element}".freeze
+      end
+    end
+    
+    module ClassMethods 
+      def model_name 
+        @_model_name ||= Name.new
+      end 
+    end 
   end
 end

data/lib/meta_search/searches/active_record.rb

@@ -1,18 +1,95 @@
-require 'meta_search/searches/base'
-require 'active_record'
+require 'active_support/concern'
+require 'meta_search/method'
+require 'meta_search/builder'
 
 module MetaSearch::Searches
   module ActiveRecord
-    include MetaSearch::Searches::Base
+    extend ActiveSupport::Concern
     
-    # 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
+    included do
+      class_attribute :_metasearch_include_attributes, :_metasearch_exclude_attributes
+      class_attribute :_metasearch_include_associations, :_metasearch_exclude_associations
+      class_attribute :_metasearch_methods
+      self._metasearch_include_attributes =
+        self._metasearch_exclude_attributes =
+        self._metasearch_exclude_associations =
+        self._metasearch_include_associations = []
+      self._metasearch_methods = {}
+        
+      singleton_class.instance_eval do
+        alias_method :metasearch_include_attr, :attr_searchable
+        alias_method :metasearch_exclude_attr, :attr_unsearchable
+        alias_method :metasearch_include_assoc, :assoc_searchable
+        alias_method :metasearch_exclude_assoc, :assoc_unsearchable
+      end
+    end
+
+    module ClassMethods
+      # Prepares the search to run against your model. Returns an instance of
+      # MetaSearch::Builder, which behaves pretty much like an ActiveRecord::Relation,
+      # in that it doesn't actually query the database until you do something that
+      # requires it to do so.
+      def search(opts = {})
+        opts ||= {} # to catch nil params
+        search_options = opts.delete(:search_options) || {}
+        builder = MetaSearch::Builder.new(self, search_options)
+        builder.build(opts)
+      end
+
+      private
+      
+      # Excludes model attributes from searchability. This means that searches can't be created against
+      # these columns, whether the search is based on this model, or the model's attributes are being
+      # searched by association from another model. If a Comment <tt>belongs_to :article</tt> but declares
+      # <tt>attr_unsearchable :user_id</tt> then <tt>Comment.search</tt> won't accept parameters
+      # like <tt>:user_id_equals</tt>, nor will an Article.search accept the parameter
+      # <tt>:comments_user_id_equals</tt>.
+      def attr_unsearchable(*args)
+        args.flatten.each do |attr|
+          attr = attr.to_s
+          raise(ArgumentError, "No persisted attribute (column) named #{attr} in #{self}") unless self.columns_hash.has_key?(attr)
+          self._metasearch_exclude_attributes = (self._metasearch_exclude_attributes + [attr]).uniq
+        end
+      end
+
+      # Like <tt>attr_unsearchable</tt>, but operates as a whitelist rather than blacklist. If both
+      # <tt>attr_searchable</tt> and <tt>attr_unsearchable</tt> are present, the latter
+      # is ignored.
+      def attr_searchable(*args)
+        args.flatten.each do |attr|
+          attr = attr.to_s
+          raise(ArgumentError, "No persisted attribute (column) named #{attr} in #{self}") unless self.columns_hash.has_key?(attr)
+          self._metasearch_include_attributes = (self._metasearch_include_attributes + [attr]).uniq
+        end
+      end
+      
+      # Excludes model associations from searchability. This mean that searches can't be created against
+      # these associations. An article that <tt>has_many :comments</tt> but excludes comments from
+      # searching by declaring <tt>assoc_unsearchable :comments</tt> won't make any of the
+      # <tt>comments_*</tt> methods available.
+      def assoc_unsearchable(*args)
+        args.flatten.each do |assoc|
+          assoc = assoc.to_s
+          raise(ArgumentError, "No such association #{assoc} in #{self}") unless self.reflect_on_all_associations.map {|a| a.name.to_s}.include?(assoc)
+          self._metasearch_exclude_associations = (self._metasearch_exclude_associations + [assoc]).uniq
+        end
+      end
+      
+      # As with <tt>attr_searchable</tt> this is the whitelist version of
+      # <tt>assoc_unsearchable</tt>
+      def assoc_searchable(*args)
+        args.flatten.each do |assoc|
+          assoc = assoc.to_s
+          raise(ArgumentError, "No such association #{assoc} in #{self}") unless self.reflect_on_all_associations.map {|a| a.name.to_s}.include?(assoc)
+          self._metasearch_include_associations = (self._metasearch_include_associations + [assoc]).uniq
+        end
+      end
+      
+      def search_methods(*args)
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        args.flatten.map(&:to_s).each do |arg|
+          self._metasearch_methods[arg] = MetaSearch::Method.new(arg, opts)
+        end
       end
     end
   end