meta_search_hub 1.1.3

data/lib/meta_search/builder.rb

@@ -0,0 +1,316 @@
+require 'polyamorous'
+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, :relation, :search_key, :search_attributes, :join_dependency, :errors, :options
+    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_or_relation, opts = {})
+      opts = opts.dup
+      @relation = base_or_relation.scoped
+      @base = @relation.klass
+      @search_key = (opts.delete(:search_key) || 'search').to_s
+      @options = opts  # Let's just hang on to other options for use in authorization blocks
+      @join_type = opts[:join_type] ||  Arel::Nodes::OuterJoin
+      @join_type = get_join_type(@join_type)
+      @join_dependency = build_join_dependency(@relation)
+      @search_attributes = {}
+      @errors = ActiveModel::Errors.new(self)
+    end
+
+    def get_column(column, base = @base)
+      base.columns_hash[column.to_s] if base._metasearch_attribute_authorized?(column, self)
+    end
+
+    def get_association(assoc, base = @base)
+      base.reflect_on_association(assoc.to_sym) if base._metasearch_association_authorized?(assoc, self)
+    end
+
+    def get_attribute(name, parent = @join_dependency.join_base)
+      attribute = nil
+      if get_column(name, parent.active_record)
+        attribute = parent.table[name]
+      elsif (segments = name.to_s.split(/_/)).size > 1
+        remainder = []
+        found_assoc = nil
+        while remainder.unshift(segments.pop) && segments.size > 0 && !found_assoc do
+          if found_assoc = get_association(segments.join('_'), parent.active_record)
+            if found_assoc.options[:polymorphic]
+              unless delimiter = remainder.index('type')
+                raise PolymorphicAssociationMissingTypeError, "Polymorphic association specified without a type"
+              end
+              polymorphic_class, attribute_name = remainder[0...delimiter].join('_'),
+                                                  remainder[delimiter + 1...remainder.size].join('_')
+              polymorphic_class = polymorphic_class.classify.constantize
+              join = build_or_find_association(found_assoc.name, parent, polymorphic_class)
+              attribute = get_attribute(attribute_name, join)
+            else
+              join = build_or_find_association(found_assoc.name, parent, found_assoc.klass)
+              attribute = get_attribute(remainder.join('_'), join)
+            end
+          end
+        end
+      end
+      attribute
+    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(option_hash)
+      opts = option_hash.dup || {}
+      @relation = @base.scoped
+      opts.stringify_keys!
+      opts = collapse_multiparameter_options(opts)
+      assign_attributes(opts)
+      self
+    end
+
+    def respond_to?(method_id, include_private = false)
+      return true if super
+
+      method_name = method_id.to_s
+      if RELATION_METHODS.map(&:to_s).include?(method_name)
+        true
+      elsif method_name.match(/^meta_sort=?$/)
+        true
+      elsif match = method_name.match(/^(.*)\(([0-9]+).*\)$/)
+        method_name, index = match.captures
+        respond_to?(method_name)
+      elsif matches_named_method(method_name) || matches_attribute_method(method_name)
+        true
+      else
+        false
+      end
+    end
+
+    private
+
+    def assign_attributes(opts)
+      opts.each_pair do |k, v|
+        self.send("#{k}=", v)
+      end
+    end
+
+    def gauge_depth_of_join_association(ja)
+      1 + (ja.respond_to?(:parent) ? gauge_depth_of_join_association(ja.parent) : 0)
+    end
+
+    def method_missing(method_id, *args, &block)
+      method_name = method_id.to_s
+      if method_name =~ /^meta_sort=?$/
+        (args.any? || method_name =~ /=$/) ? set_sort(args.first) : get_sort
+      elsif match = method_name.match(/^(.*)\(([0-9]+).*\)$/) # Multiparameter reader
+        method_name, index = match.captures
+        vals = self.send(method_name)
+        vals.is_a?(Array) ? vals[index.to_i - 1] : nil
+      elsif match = matches_named_method(method_name)
+        (args.any? || method_name =~ /=$/) ? set_named_method_value(match, args.first) : get_named_method_value(match)
+      elsif match = matches_attribute_method(method_id)
+        attribute, predicate = match.captures
+         (args.any? || method_name =~ /=$/) ? set_attribute_method_value(attribute, predicate, args.first) : get_attribute_method_value(attribute, predicate)
+      else
+        super
+      end
+    end
+
+    def matches_named_method(name)
+      method_name = name.to_s.sub(/\=$/, '')
+      return method_name if @base._metasearch_method_authorized?(method_name, self)
+    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, predicate = match.captures
+      attributes = attribute.split(/_or_/)
+      if attributes.all? {|a| where.types.include?(column_type(a))}
+        return match
+      end
+      nil
+    end
+
+    def get_sort
+      search_attributes['meta_sort']
+    end
+
+    def set_sort(val)
+      return if val.blank?
+      column, direction = val.split('.')
+      direction ||= 'asc'
+      if ['asc','desc'].include?(direction)
+        if @base.respond_to?("sort_by_#{column}_#{direction}")
+          search_attributes['meta_sort'] = val
+          @relation = @relation.send("sort_by_#{column}_#{direction}")
+        elsif attribute = get_attribute(column)
+          search_attributes['meta_sort'] = val
+          @relation = @relation.order(attribute.send(direction).to_sql)
+        elsif column.scan('_and_').present?
+          attribute_names = column.split('_and_')
+          attributes = attribute_names.map {|n| get_attribute(n)}
+          if attribute_names.size == attributes.compact.size # We found all attributes
+            search_attributes['meta_sort'] = val
+            attributes.each do |attribute|
+              @relation = @relation.order(attribute.send(direction).to_sql)
+            end
+          end
+        end
+      end
+    end
+
+    def get_named_method_value(name)
+      search_attributes[name]
+    end
+
+    def set_named_method_value(name, val)
+      meth = @base._metasearch_methods[name][:method]
+      search_attributes[name] = meth.cast_param(val)
+      if meth.validate(search_attributes[name])
+        return_value = meth.evaluate(@relation, search_attributes[name])
+        if return_value.is_a?(ActiveRecord::Relation)
+          @relation = return_value
+        else
+          raise NonRelationReturnedError, "Custom search methods must return an ActiveRecord::Relation. #{name} returned a #{return_value.class}"
+        end
+      end
+    end
+
+    def get_attribute_method_value(attribute, predicate)
+      search_attributes["#{attribute}_#{predicate}"]
+    end
+
+    def set_attribute_method_value(attribute, predicate, val)
+      where = Where.new(predicate)
+      attributes = attribute.split(/_or_/)
+      search_attributes["#{attribute}_#{predicate}"] = cast_attributes(where.cast || column_type(attributes.first), val)
+      if where.validate(search_attributes["#{attribute}_#{predicate}"])
+        arel_attributes = attributes.map {|a| get_attribute(a)}
+        @relation = where.evaluate(@relation, arel_attributes, search_attributes["#{attribute}_#{predicate}"])
+      end
+    end
+
+    def column_type(name, base = @base, depth = 1)
+      type = nil
+      if column = get_column(name, base)
+        type = column.type
+      elsif (segments = name.split(/_/)).size > 1
+        type = type_from_association_segments(segments, base, depth)
+      end
+      type
+    end
+
+    def type_from_association_segments(segments, base, depth)
+      remainder = []
+      found_assoc = nil
+      type = nil
+      while remainder.unshift(segments.pop) && segments.size > 0 && !found_assoc do
+        if found_assoc = get_association(segments.join('_'), base)
+          depth += 1
+          raise JoinDepthError, "Maximum join depth of #{MAX_JOIN_DEPTH} exceeded." if depth > MAX_JOIN_DEPTH
+          if found_assoc.options[:polymorphic]
+            unless delimiter = remainder.index('type')
+              raise PolymorphicAssociationMissingTypeError, "Polymorphic association specified without a type"
+            end
+            polymorphic_class, attribute_name = remainder[0...delimiter].join('_'),
+                                                remainder[delimiter + 1...remainder.size].join('_')
+            polymorphic_class = polymorphic_class.classify.constantize
+            type = column_type(attribute_name, polymorphic_class, depth)
+          else
+            type = column_type(remainder.join('_'), found_assoc.klass, depth)
+          end
+        end
+      end
+      type
+    end
+
+    def build_or_find_association(name, parent = @join_dependency.join_base, klass = nil)
+      found_association = @join_dependency.join_associations.detect do |assoc|
+        assoc.reflection.name == name &&
+        assoc.parent == parent &&
+        (!klass || assoc.reflection.klass == klass)
+      end
+      unless found_association
+        @join_dependency.send(:build, Polyamorous::Join.new(name, @join_type, klass), parent)
+        found_association = @join_dependency.join_associations.last
+        # Leverage the stashed association functionality in AR
+        @relation = @relation.joins(found_association)
+      end
+
+      found_association
+    end
+
+    def build_join_dependency(relation)
+      buckets = relation.joins_values.group_by do |join|
+        case join
+        when String
+          'string_join'
+        when Hash, Symbol, Array
+          'association_join'
+        when ::ActiveRecord::Associations::JoinDependency::JoinAssociation
+          'stashed_join'
+        when Arel::Nodes::Join
+          'join_node'
+        else
+          raise 'unknown class: %s' % join.class.name
+        end
+      end
+
+      association_joins         = buckets['association_join'] || []
+      stashed_association_joins = buckets['stashed_join'] || []
+      join_nodes                = buckets['join_node'] || []
+      string_joins              = (buckets['string_join'] || []).map { |x|
+        x.strip
+      }.uniq
+
+      join_list = relation.send :custom_join_ast, relation.table.from(relation.table), string_joins
+
+      join_dependency = ::ActiveRecord::Associations::JoinDependency.new(
+        relation.klass,
+        association_joins,
+        join_list
+      )
+
+      join_nodes.each do |join|
+        join_dependency.alias_tracker.aliased_name_for(join.left.name.downcase)
+      end
+
+      join_dependency.graft(*stashed_association_joins)
+    end
+
+    def get_join_type(opt_join)
+      # Allow "inner"/:inner and "upper"/:upper
+      if opt_join.to_s.upcase == 'INNER'
+        opt_join = Arel::Nodes::InnerJoin
+      elsif opt_join.to_s.upcase == 'OUTER'
+        opt_join = Arel::Nodes::OuterJoin
+      end
+      # Default to trusting what the user gave us
+      opt_join
+    end
+  end
+end

data/lib/meta_search/exceptions.rb

@@ -0,0 +1,17 @@
+module MetaSearch
+  # Raised when type casting for a column fails.
+  class TypeCastError < StandardError; end
+
+  # Raised if you don't return a relation from a custom search method.
+  class NonRelationReturnedError < StandardError; end
+
+  # Raised if you try to access a relation that's joining too many tables to itself.
+  # This is designed to prevent a malicious user from accessing something like
+  # :developers_company_developers_company_developers_company_developers_company_...,
+  # resulting in a query that could cause issues for your database server.
+  class JoinDepthError < StandardError; end
+
+  # Raised if you try to search on a polymorphic belongs_to association without specifying
+  # its type.
+  class PolymorphicAssociationMissingTypeError < StandardError; end
+end

data/lib/meta_search/helpers/form_builder.rb

@@ -0,0 +1,166 @@
+require 'action_view'
+require 'action_view/template'
+module MetaSearch
+  Check = Struct.new(:box, :label)
+
+  module Helpers
+    module FormBuilder
+
+      def self.included(base)
+        # Only take on the check_boxes method names if someone else (Hi, José!) hasn't grabbed them.
+        alias_method :check_boxes, :checks unless base.method_defined?(:check_boxes)
+        alias_method :collection_check_boxes, :collection_checks unless base.method_defined?(: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.checks :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 checks like so:
+      #   <h4>How many heads?</h4>
+      #   <p>
+      #     <% f.checks(: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 checks(method, choices = [], options = {}, &block)
+        unless choices.first.respond_to?(:first) && choices.first.respond_to?(:last)
+          raise ArgumentError, 'invalid choice array specified'
+        end
+        collection_checks(method, choices, :last, :first, options, &block)
+      end
+
+      # Just like +checks+, but this time you can pass in a collection, value, and text method,
+      # as with collection_select.
+      #
+      # Example:
+      #
+      #   <% f.collection_checks :head_sizes_in, HeadSize.all,
+      #       :id, :name, :class => 'headcheck' do |check| %>
+      #     <%= check.box %> <%= check.label %>
+      #   <% end %>
+      def collection_checks(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
+
+      # Creates a sort link for the MetaSearch::Builder the form is created against.
+      # Useful shorthand if your results happen to reside in the context of your
+      # form_for block.
+      # Sample usage:
+      #
+      #   <%= f.sort_link :name %>
+      #   <%= f.sort_link :name, 'Company Name' %>
+      #   <%= f.sort_link :name, :class => 'name_sort' %>
+      #   <%= f.sort_link :name, 'Company Name', :class => 'company_name_sort' %>
+      def sort_link(attribute, *args)
+        @template.sort_link @object, attribute, *args
+      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,24 @@
+module MetaSearch
+  module Helpers
+    module FormHelper
+      def apply_form_for_options!(object_or_array, options)
+        if object_or_array.is_a?(MetaSearch::Builder)
+          builder = object_or_array
+          options[:url] ||= polymorphic_path(object_or_array.base)
+        elsif object_or_array.is_a?(Array) && (builder = object_or_array.detect {|o| o.is_a?(MetaSearch::Builder)})
+          options[:url] ||= polymorphic_path(object_or_array.map {|o| o.is_a?(MetaSearch::Builder) ? o.base : o})
+        else
+          super 
+          return
+        end
+
+        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)
+      end
+    end
+  end
+end

data/lib/meta_search/helpers/url_helper.rb

@@ -0,0 +1,66 @@
+module MetaSearch
+  module Helpers
+    module UrlHelper
+
+      # Generates a column sort link for a given attribute of a MetaSearch::Builder object.
+      # The link maintains existing options for the sort as parameters in the URL, and
+      # sets a meta_sort parameter as well. If the first parameter after the attribute name
+      # is not a hash, it will be used as a string for alternate link text. If a hash is
+      # supplied, it will be passed to link_to as an html_options hash. The link will
+      # be assigned two css classes: sort_link and one of "asc" or "desc", depending on
+      # the current sort order. Any class supplied in the options hash will be appended.
+      #
+      # Sample usage:
+      #
+      #   <%= sort_link @search, :name %>
+      #   <%= sort_link @search, :name, 'Company Name' %>
+      #   <%= sort_link @search, :name, :class => 'name_sort' %>
+      #   <%= sort_link @search, :name, 'Company Name', :class => 'company_name_sort' %>
+      #   <%= sort_link @search, :name, :default_order => :desc %>
+      #   <%= sort_link @search, :name, 'Company Name', :default_order => :desc %>
+      #   <%= sort_link @search, :name, :class => 'name_sort', :default_order => :desc %>
+      #   <%= sort_link @search, :name, 'Company Name', :class => 'company_name_sort', :default_order => :desc %>
+
+      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 : builder.base.human_attribute_name(attr_name)
+        prev_attr, prev_order = builder.search_attributes['meta_sort'].to_s.split('.')
+
+        options = args.first.is_a?(Hash) ? args.shift.dup : {}
+        current_order = prev_attr == attr_name ? prev_order : nil
+
+        if options[:default_order] == :desc
+          new_order = current_order == 'desc' ? 'asc' : 'desc'
+        else
+          new_order = current_order == 'asc' ? 'desc' : 'asc'
+        end
+        options.delete(:default_order)
+
+        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!(
+          builder.search_key => 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'
+          '&#9650;'
+        elsif order == 'desc'
+          '&#9660;'
+        else
+          nil
+        end
+      end
+    end
+  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/locale/en.yml

@@ -0,0 +1,24 @@
+en:
+  meta_search:
+    or: 'or'
+    predicates:
+      equals: "%{attribute} equals"
+      does_not_equal: "%{attribute} doesn't equal"
+      contains: "%{attribute} contains"
+      does_not_contain: "%{attribute} doesn't contain"
+      starts_with: "%{attribute} starts with"
+      does_not_start_with: "%{attribute} doesn't start with"
+      ends_with: "%{attribute} ends with"
+      does_not_end_with: "%{attribute} doesn't end with"
+      greater_than: "%{attribute} greater than"
+      less_than: "%{attribute} less than"
+      greater_than_or_equal_to: "%{attribute} greater than or equal to"
+      less_than_or_equal_to: "%{attribute} less than or equal to"
+      in: "%{attribute} is one of"
+      not_in: "%{attribute} isn't one of"
+      is_true: "%{attribute} is true"
+      is_false: "%{attribute} is false"
+      is_present: "%{attribute} is present"
+      is_blank: "%{attribute} is blank"
+      is_null: "%{attribute} is null"
+      is_not_null: "%{attribute} isn't null"