wvanbergen edited this page Nov 10, 2014 · 33 revisions

scoped_search is a simple Rails plugin that 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.


Installing scoped_search

To install the gem simply add the following line to the Gemfile, and run bundle install

gem 'scoped_search'

To use the auto completer javascript based ui you’ll need to include jquery-ui, there are several ways to include jquery-ui, for example, add to the Gemfile:

gem 'jquery-rails'
gem 'jquery-ui-rails'

Add the following tag to your view:

<%= text_field_tag("search", value,
                   :class => 'autocomplete-input form-control',
                   :autocomplete => 'off',
                   :placeholder  => 'Search ..',
                   :'data-url'   => "#{path}/auto_complete_search")

And add this to your application.js:

//= require jquery-ui/completer

// run the auto completer script on first focus
$(document).on('focus', "#search", function(e) {
    if ($(".autocomplete-clear").length == 0) {

In your application.css, require the corresponding CSS module:
*= require jquery-ui/completer

Note: Older versions of jquery-ui used jquery.ui.completer syntax for the require

Additional resources

Support for different databases

Because the library generates standard SQL, it should work for all databases that respect the SQL standard. However, there are small differences between the different databases that may warrant different handling.

Scoped search comes with adapters for SQLite, MySQL and PostgreSQL to ensure consistent results across databases. We will only accept support for open source databases to the gem. However, some plugins exists to improve scoped_search’s results for other databases as well.

- Oracle: https://github.com/wvanbergen/scoped_search-oracle_enhanced
- H2: https://github.com/wvanbergen/scoped_search-h2


This plugin is released under the MIT license.

If you want to hack on this plugin or change it to suit your needs, see the CONTRIBUTING.rdoc for some pointers.