Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Object-based searching (and more) for simply creating search forms.

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.rdoc

MetaSearch

MetaSearch is extensible searching for your form_for enjoyment. It “wraps” one of your ActiveRecord models, providing methods that allow you to build up search conditions against that model, and has a few extra form helpers to simplify sorting and supplying multiple parameters to your condition methods as well.

Getting Started

In your Gemfile:

gem "meta_search"  # Last officially released gem
# gem "meta_search", :git => "git://github.com/ernie/meta_search.git" # Track git repo

or, to install as a plugin:

rails plugin install git://github.com/ernie/meta_search.git

In your controller:

def index
  @search = Article.search(params[:search])
  @articles = @search.all   # or @search.relation to lazy load in view
end

In your view:

<%= form_for @search, :url => articles_path, :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

Narrowing the scope of a search

While the most common use case is to simply call Model.search(params[:search]), there may be times where you want to scope your search more tightly. For instance, only allowing users to search their own projects (assuming a current_user method returning the current user):

@search = current_user.projects.search(params[:search])

Or, you can build up any relation you like and call the search method on that object:

@projects_with_awesome_users_search =
  Project.joins(:user).where(:users => {:awesome => true}).search(params[:search])

Multi-level associations

MetaSearch will allow you to traverse your associations in one form, generating the necessary joins along the way. If you have the following models…

class Company < ActiveRecord::Base
  has_many :developers
end

class Developer < ActiveRecord::Base
  belongs_to :company
  has_many :notes
end

…you can do this in your form to search your companies by developers with certain notes:

<%= f.text_field :developers_notes_note_contains %>

You can travel forward and back through the associations, so this would also work (though be entirely pointless in this case):

<%= f.text_field :developers_notes_developer_company_name_contains %>

However, to prevent abuse, this is limited to associations of a total “depth” of 5 levels. This means that while starting from a Company model, as above, you could do Company -> :developers -> :notes -> :developer -> :company, which has gotten you right back where you started, but “travels” through 5 models total.

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 (/config/initializers/meta_search.rb, for instance) and add lines like:

MetaSearch::Where.add :between, :btw,
  :predicate => :in,
  :types => [:integer, :float, :decimal, :date, :datetime, :timestamp, :time],
  :formatter => Proc.new {|param| Range.new(param.first, param.last)},
  :validator => Proc.new {|param|
    param.is_a?(Array) && !(param[0].blank? || param[1].blank?)
  }

See MetaSearch::Where for info on the supported options.

Accessing custom search methods (and named scopes!)

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 search_methods 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 search_methods:

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. Regarding :types: 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.

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 %>

multiparameter_field 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.

Compound conditions (any/all)

All Where types automatically get an “any” and “all” variant. This has the same name and aliases as the original, but is suffixed with _any and _all, for an “OR” or “AND” search, respectively. So, if you want to provide the user with 5 different search boxes to enter possible article titles:

<%= f.multiparameter_field :title_contains_any,
      *5.times.inject([]) {|a, b| a << {:field_type => :text_field}} +
      [:size => 10] %>

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. They can be called with or without a block. Without a block, you get an array of MetaSearch::Check objects to do with as you please.

With a block, each check is yielded to your template, like so:

<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>

Again, full documentation is in MetaSearch::Helpers::FormBuilder.

Sorting columns

If you'd like to sort by a specific column in your results (the attributes of the base model) or an association column then supply the meta_sort parameter in your form. The parameter takes the form column.direction where column is the column name or underscore-separated association_column combination, and direction is one of “asc” or “desc” for ascending or descending, respectively.

Normally, you won't supply this parameter yourself, but instead will use the helper method sort_link in your views, like so:

<%= sort_link @search, :title %>
<%= sort_link @search, :created_at %>

The @search object is the instance of MetaSearch::Builder you got back earlier from your controller. The other required parameter is the attribute name itself. Optionally, you can provide a string as a 3rd parameter to override the default link name, and then additional hashed for the options and html_options hashes for link_to.

All sort_link-generated links will have the CSS class sort_link, as well as a directional class (ascending or descending) if the link is for a currently sorted column, for your styling enjoyment.

This feature should hopefully help out those of you migrating from Searchlogic, and a thanks goes out to Ben Johnson for the HTML entities used for the up and down arrows, which provide a nice default look.

Including/excluding attributes and associations

If you'd like to allow only certain associations or attributes to be searched, you can do so inside your models

class Article < ActiveRecord::Base
  attr_searchable :some_public_data, :some_more_searchable_stuff
  assoc_searchable :search_this_association_why_dontcha
end

If you'd rather blacklist attributes and associations rather than whitelist, use the attr_unsearchable and assoc_unsearchable method instead. If a whitelist is supplied, it takes precedence.

Excluded attributes on a model will be honored across associations, so if an Article has_many :comments and the Comment model looks something like this:

class Comment < ActiveRecord::Base
  validates_presence_of :user_id, :body
  attr_unsearchable :user_id
end

Then your call to Article.search will allow :comments_body_contains but not :comments_user_id_equals to be passed.

Contributions

There are several ways you can help MetaSearch continue to improve.

  • Use MetaSearch in your real-world projects and submit bug reports or feature suggestions.

  • Better yet, if you’re so inclined, fix the issue yourself and submit a patch! Or you can fork the project on GitHub and send me a pull request (please include tests!)

  • If you like MetaSearch, spread the word. More users == more eyes on code == more bugs getting found == more bugs getting fixed (hopefully!)

  • Lastly, if MetaSearch has saved you hours of development time on your latest Rails gig, and you’re feeling magnanimous, please consider making a donation to the project. I have spent hours of my personal time coding and supporting MetaSearch, and your donation would go a great way toward justifying that time spent to my loving wife. :)

Copyright

Copyright © 2010 Ernie Miller. See LICENSE for details.

Something went wrong with that request. Please try again.