= scoped_search

The <b>scoped_search</b> Rails plugin makes it easy to search your ActiveRecord models. Searching is 
performed using a query string, which should be passed to the named_scope *search_for* that uses SQL 
<tt>LIKE %keyword%</tt> conditions for searching (ILIKE for Postgres). You can specify what fields 
should be used for searching.

== Installing

The recommended method to enable scoped_search in your project is adding the scoped_search gem to your environment. Add the following code to your Rails configuration in <tt>config/environment.rb</tt>:

  Rails::Initializer.run do |config|
    ...
    config.gem 'wvanbergen-scoped_search', :lib => 'scoped_search', 
                   source => 'http://gems.github.com/'
  end

Run <tt>sudo rake gems:install</tt> to install the gem.

Another alternative is to install scoped_search as a Rails plugin:

  script/plugin install git://github.com/wvanbergen/scoped_search.git

== Usage

First, you have to specify in what columns should be searched:

  class User < ActiveRecord::Base
    searchable_on :first_name, :last_name
  end


Now, the <b>search_for</b> scope is available for queries. You should pass a query string to the scope. 
This can be empty or nil, in which case all no search conditions are set (and all records will be returned).

  User.search_for(params[:q]).each { |project| ... }


You can also search on associate models.  This works with <b>belongs_to</b>, <b>has_one</b>, <b>has_many</b>, 
<b>has_many :through</b>, and <b>HABTM</b>.  For example if a User <b>has_many</b> Notes (title, content, created_at, updated_at)

  class User < ActiveRecord::Base
    has_many: notes
    searchable_on :first_name, :last_name, :notes_title, :notes_content
  end

The search query language is simple. It supports these constructs:
* <b>words:</b> <tt>some search keywords</tt>
* <b>phrases:</b> <tt>"a single search phrase"</tt>
* <b>negation:</b> <tt>"look for this" -"but do not look for this phrase and this" -word</tt>
* <b>OR words/phrases:</b> word/phrase OR word/phrase.  Example: <tt>"Hello World" OR "Hello Moon"</tt>
* <b>dates:</b> mm/dd/yyyy, dd/mm/yyyy, yyyy/mm/dd, yyyy-mm-dd
* <b>date ranges:</b> > date, >= date, < date, <= date, date TO date.  Examples: <tt>> 30/05/1983</tt>, <tt>< 2009-01-30</tt>

This functionality is build on <tt>named_scope</tt>. The searchable_on statement creates 
a named_scope *search_for*. Because of this, you can actually chain the call with
other scopes. For example, this can be very useful if you only want to search in 
projects that are accessible by a given user.

  class Project < ActiveRecord::Base
    searchable_on :name, :description
    named_scope :accessible_by, lambda { |user| ... }
  end

  # using chained named_scopes and will_paginate
  Project.accessible_by(current_user).search_for(params[:q]).paginate(:page => params[:page], :include => :tasks)

== Additional resources

* Source code: http://github.com/wvanbergen/scoped_search/tree/master
* Project wiki: http://wiki.github.com/wvanbergen/scoped_search
* RDoc documentation: http://wvanbergen.github.com/scoped_search
* wvanbergen's blog posts: http://techblog.floorplanner.com/tag/scoped_search

== License

This plugin is released under the MIT license. Please contact weshays (http://github.com/weshays) 
or wvanbergen (http://github.com/wvanbergen) for any questions.