= 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 <tt>search_for</tt>. Based on a definition in what fields to
look, it will build query conditions and return those as a named scope.

Scoped search is great if you want to offer a simple search box to your users
and build a query based on the search string they enter. If you want to build a
more complex search form with multiple fields, searchlogic (see
http://github.com/binarylogic/searchlogic) may be a good choice for you.

== 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>, and run <tt>rake
gems:install</tt> to install the gem.:

  Rails::Initializer.run do |config|
    ...
    config.gem 'scoped_search'
  end

Alternatively, install scoped search as a Rails plugin (*deprecated*):

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

== Usage

Scoped search requires you to define the fields you want to search in:

  class User < ActiveRecord::Base
    scoped_search :on => [:first_name, :last_name]
  end

For more information about options and using fields from relations, see the
project wiki on search definitions:
http://github.com/wvanbergen/scoped_search/wiki/search-definition

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('my search string').each { |user| ... }

The result is returned as <tt>named_scope</tt>. Because of this, you can
actually chain the call with other scopes, or with will_paginate. An example:

  class Project < ActiveRecord::Base
    searchable_on :name, :description
    named_scope :public, :conditions => {:public => true }
  end

  # using chained named_scopes and will_paginate in your controller
  Project.public.search_for(params[:q]).paginate(:page => params[:page], :include => :tasks)

=== Search profiles

If you include a :profile option to the scoped_searchcall, the fields specified will only
be searched when you include this :profile into the search_for command as well:

  class User < ActiveRecord::Base
    scoped_search :on => :public_information
    scoped_search :on => :private_information, :profile => :members
  end

This will only search the :public_information column:

  User.search_for('blah blah blah')
  
And this will only search the :private_information column:

  User.search_for('blah blah blah', :profile => :members)

=== More information

More information about usage can be found in the project wiki:
http://github.com/wvanbergen/scoped_search/wiki/usage

== Query language

The search query language is simple, but supports several constructs to support
more complex queries:

words::         require every word to be present, e.g.: <tt>some search keywords</tt>

phrases::       use quotes for multi-word phrases, e.g. <tt>"police car"</tt>

negation::      look for "everything but", e.g. <tt>police -uniform</tt>, <tt>-"police car"</tt>,
                <tt>police NOT car</tt>

logical keywords:: make logical constructs using AND, OR, &&, ||, &, | operators, e.g.
                   <tt>uniform OR car</tt>, <tt>scoped && search</tt>

parentheses:: to structure logic e.g. <tt>"police AND (uniform OR car)"</tt>

comparison operators:: to search in numerical or temporal fields, e.g.
                       <tt>> 22</tt>, <tt>< 2009-01-01</tt>

explicit fields::  search only in the given field. e.g. <tt>username = root</tt>,
                   <tt>created_at > 2009-01-01</tt>

NULL checks::   using the <tt>set?</tt> and <tt>null?</tt> operator with a field name, e.g.
                <tt>null? graduated_at</tt>, <tt>set? parent_id</tt>

A complex query example to look for Ruby on Rails programmers without cobol
experience, over 18 years old, with a recently updated record and a non-lame
nickname:

  ("Ruby" OR "Rails") -cobol, age >= 18, updated_at > 2009-01-01 && nickname !~ l33t

For more info, see the the project wiki: http://github.com/wvanbergen/scoped_search/wiki/query-language

== Additional resources

* Source code: http://github.com/wvanbergen/scoped_search/tree
* Project wiki: http://github.com/wvanbergen/scoped_search/wiki
* Issue tracker: http://github.com/wvanbergen/scoped_search/issues
* RDoc documentation: http://rdoc.info/projects/wvanbergen/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.