wvanbergen / scoped_search

h1. "scoped_search":github.com/wvanbergen/scoped_search/tree/master

This simple plugin will make 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 %LIKE% conditions for searching (ILIKE for Postgres). You can specify what fields should be used for searching.

• "scoped_search installation":#INSTALLATION
• "scoped_search usage":#USAGE
• "scoped_search license":#LICENSE

<a id="INSTALLATION"/> </a> h2. Installing scoped_search

<pre><code> gem install wvanbergen-scoped_search

</code></pre>

<a id="USAGE"/> </a> h2. Usage

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

<pre><code> class User < ActiveRecord::Base

  searchable_on :first_name, :last_name

end

</code></pre>

Now, the search_for 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).

<pre><code> User.search_for(params[:q]).each { |project| … }

</code></pre>

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

<pre><code> class User < ActiveRecord::Base

  has_many: notes
  searchable_on :first_name, :last_name, :notes_title, :notes_content

end

</code></pre>

The search query language is simple. It supports these constructs:

• words: some search keywords
• phrases: "a single search phrase"
• negation: "look for this" -"but do not look for this phrase and this" -word
• OR words/phrases: word/phrase OR word/phrase. Example: "Hello World" OR "Hello Moon"
• dates: mm/dd/yyyy, dd/mm/yyyy, yyyy/mm/dd, yyyy-mm-dd
• date ranges: > date, >= date, < date, <= date, date TO date. Examples: > mm/dd/yyyy, < yyyy-mm-dd

This functionality is build on named_scope. 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.

<pre><code> 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)

</code></pre>

<a id="LICENSE"/> </a> h2. License

This plugin is released under the MIT license. Please contact (willem AT vanbergen DOT org) if you have any suggestions or remarks.