Every repository with this icon (
) is private.
Every repository with this icon (
) is public.
Scoped search
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 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 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 config/environment.rb, and run rake gems:install to install the gem.:
Rails::Initializer.run do |config|
...
config.gem 'scoped_search', :source => 'http://gemcutter.org/'
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: wiki.github.com/wvanbergen/scoped_search/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)
More information about usage can be found in the project wiki: wiki.github.com/wvanbergen/scoped_search/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: wiki.github.com/wvanbergen/scoped_search/query-language
Additional resources
- Source code: github.com/wvanbergen/scoped_search/tree/master
- Project wiki: wiki.github.com/wvanbergen/scoped_search
- RDoc documentation: wvanbergen.github.com/scoped_search
- wvanbergen’s blog posts: techblog.floorplanner.com/tag/scoped_search
License
This plugin is released under the MIT license. Please contact weshays (github.com/weshays) or wvanbergen (github.com/wvanbergen) for any questions.
