Scoped search <img src=“https://secure.travis-ci.org/wvanbergen/scoped_search.png” />¶ ↑

The scoped_search gem 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.

Preview¶ ↑

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: theme github.com/abenari/search-demo2

Installing¶ ↑

Add the following line in your Gemfile, and run bundle install:

gem "scoped_search"

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: 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
  scoped_search 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_search call, 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: 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.: some search keywords
phrases: use quotes for multi-word phrases, e.g. "police car"
negation: look for “everything but”, e.g. police -uniform, -"police car", police NOT car
logical keywords: make logical constructs using AND, OR, &&, ||, &, | operators, e.g. uniform OR car, scoped && search
parentheses: to structure logic e.g. "police AND (uniform OR car)"
comparison operators: to search in numerical or temporal fields, e.g. > 22, < 2009-01-01
explicit fields: search only in the given field. e.g. username = root, created_at > 2009-01-01
NULL checks: 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

Additional resources¶ ↑

Project wiki: github.com/wvanbergen/scoped_search/wiki
Issue tracker: github.com/wvanbergen/scoped_search/issues
RDoc documentations: www.rubydoc.info/gems/scoped_search
Source code: github.com/wvanbergen/scoped_search
See CHANGELOG.rdoc for the changes to this library over time.
See CONTRIBUTING.rdoc if you want to report bugs, or help out on this project.

License¶ ↑

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).

alemata / scoped_search