Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Object-based searching (and more) for simply creating search forms.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Extensible searching for your form_for enjoyment.

Getting Started

Add a line to your Gemfile:

gem "meta_search"

In your controller:

def index
  @search =[:search])
  @articles = @search.all

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

MetaSearch::Where.add :between, :btw, {:condition => 'BETWEEN', :substitutions => '? AND ?'}

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


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.

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:

  <th colspan="2">How many heads?</th>
  <% f.check_boxes :number_of_heads_in,
     [['One', 1], ['Two', 2], ['Three', 3]], :class => 'checkboxy' do |c| %>
       <td><%= c[:check_box] %></td>
       <td><%= c[:label] %></td>
  <% end %>

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

You get the idea. 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:

Comment < ActiveRecord::Base
  validates_presence_of :user_id, :body
  metasearch_exclude_attr :user_id

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


Copyright © 2010 Ernie Miller. See LICENSE for details.

Something went wrong with that request. Please try again.