The scoped_search 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
. 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 yet powerful search box to your users and build a query based on the search string they enter. It comes with a built-in search syntax auto-completer and a value auto-completer. It also comes with a set of helpers that makes it easy to create a clean web UI with sorting and an ajax auto-completer.
A demo application using the scoped search can be found here: github.com/abenari/scoped_search_demo_app A running version of the demo application can be found here: scope-search-demo.heroku.com A Rails 3.2 demo with assets pipeline and twitter bootstrap theame github.com/abenari/search-demo2
For a Rails 3 application add the following line
in your Gemfile, and run bundle install
:
gem "scoped_search"
For Rails 2 Add the following code to your Rails configuration in
config/environment.rb
, and run rake gems:install
to install the gem.:
Rails::Initializer.run do |config| ... config.gem 'scoped_search' end
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: github.com/wvanbergen/scoped_search/wiki/search-definition
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).
User.search_for('my search string').each { |user| ... }
The result is returned as named_scope
. 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)
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 about usage can be found in the project wiki: github.com/wvanbergen/scoped_search/wiki/usage
The search query language is simple, but supports several constructs to support more complex queries:
require every word to be present, e.g.: some search keywords
use quotes for multi-word phrases, e.g. "police car"
look for “everything but”, e.g. police -uniform
,
-"police car"
, police NOT car
make logical constructs using AND, OR, &&, ||, &, | operators,
e.g. uniform OR car
, scoped && search
to structure logic e.g. "police AND (uniform OR
car)"
to search in numerical or temporal fields, e.g. > 22
,
< 2009-01-01
search only in the given field. e.g. username = root
,
created_at > 2009-01-01
using the set?
and null?
operator with a field
name, e.g. null? graduated_at
, set? parent_id
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: github.com/wvanbergen/scoped_search/wiki/query-language
Source code: github.com/wvanbergen/scoped_search/tree
Project wiki: github.com/wvanbergen/scoped_search/wiki
Issue tracker: github.com/wvanbergen/scoped_search/issues
RDoc documentation: rdoc.info/projects/wvanbergen/scoped_search
wvanbergen's blog posts: techblog.floorplanner.com/tag/scoped_search
abenari's blog: scopedsearch.wordpress.com/
This plugin is released under the MIT license (see LICENSE).
This plugin was originally developed for Floorplanner.com by Willem van Bergen (github.com/wvanbergen) with help from Wes Hays (github.com/weshays). The current maintainer is Amos Benari (github.com/abenari).