Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wvanbergen/scoped_search

Easily search you ActiveRecord models with a simple query language that converts to SQL.
https://github.com/wvanbergen/scoped_search

Last synced: 3 days ago
JSON representation

Easily search you ActiveRecord models with a simple query language that converts to SQL.

Awesome Lists containing this project

README 

        
= Scoped search {}[http://travis-ci.org/wvanbergen/scoped_search]



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: http://github.com/abenari/scoped_search_demo_app

A running version of the demo application can be found here: http://scope-search-demo.heroku.com

A Rails 3.2 demo with assets pipeline and twitter bootstrap: theme https://github.com/abenari/search-demo2



== Installing



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



  gem "scoped_search"



Scoped search 4.x supports Rails 4.2 to 5.0, with Ruby 2.0.0 or higher. Use

previous versions, e.g. 3.x to support older versions of Rails or Ruby.



== 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:

http://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:

http://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: http://github.com/wvanbergen/scoped_search/wiki/query-language



== Additional resources



* Project wiki: https://github.com/wvanbergen/scoped_search/wiki

* Issue tracker: https://github.com/wvanbergen/scoped_search/issues

* RDoc documentations: http://www.rubydoc.info/gems/scoped_search

* Source code: https://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

(https://github.com/wvanbergen) with help from Wes Hays (https://github.com/weshays).

The current maintainer is Amos Benari (https://github.com/abenari).