Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Acts As Indexed is a plugin which provides a pain-free way to add fulltext search to your Ruby on Rails app
Ruby

This branch is 1 commit ahead, 207 commits behind dougal:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
rails
test
.gitignore
CHANGELOG
MIT-LICENSE
README.rdoc
Rakefile
VERSION
acts_as_indexed.gemspec

README.rdoc

acts_as_indexed

If you find this plugin useful, please consider a donation to show your support!

www.paypal.com/cgi-bin/webscr?cmd=_send-money

Paypal address: dougal.s@gmail.com

Instructions

This plugin allows boolean-queried fulltext search to be added to any Rails app with no dependencies and minimal setup.

Resources

Install

Rails 2.x.x

./script/plugin install git://github.com/dougal/acts_as_indexed.git

Rails 3.x.x

rails plugin install git://github.com/dougal/acts_as_indexed.git

As a Gem

Despite this being slightly against the the original ethos of the project, acts_as_indexed is now available as a Gem as several people have requested it.

gem install acts_as_indexed

Make sure to specify the Gem in your environment.rb file (Rails 2.x.x), or the Gemfile (Rails 3.x.x).

No Git?

If you don't have git installed, you can download the plugin from the GitHub page (github.com/dougal/acts_as_indexed) and unpack it into the vendor/plugins directory of your rails app.

Usage

Setup

Add acts_as_indexed to the top of any models you want to index, along with a list of the fields you wish to be indexed.

class Post < ActiveRecord::Base
  acts_as_indexed :fields => [:title, :body]

  ...
end

The fields are not limited to model fields, but can be any instance method of the current model.

class User < ActiveRecord::Base
  acts_as_indexed :fields => [:address, :fullname]

  def fullname
    self.firstname + ' ' + self.lastname
  end

  ...
end

Any of the configuration options in the Further Configuration section can be added as to the acts_as_indexed method call. These will override any defaults or global configuration.

You can specify proc that needs to evaluate to true before the item gets indexed. This is useful if you only want items with a certain state to be included. The Proc is passed the current object's instance so you are able to test against that.

For example, if you have a visible column that is false if the post is hidden, or true if it is visible, you can filter the index by doing:

class Post < ActiveRecord::Base
  acts_as_indexed :fields => [:title, :body], :if => Proc.new { |post| post.visible? }
  ...
end

Searching

To search, call the with_query named scope on your model, passing a query as an argument.

# Returns array of Post objects.
my_search_results = Post.with_query('my search query')

# Chain it with any number of ActiveRecord methods and named_scopes.
my_search_results = Post.public.with_query('my search query').find(:all, :limit => 10) # return the first 10 matches which are public.

Cross-Model Search

For cross-model searching, this plugin keeps track of every model that acts_as_indexed.

class BlogPost < ActiveRecord::Base
  acts_as_indexed :fields => [:body]
end
class Article < ActiveRecord::Base
  acts_as_indexed :fields => [:content]
end
class Review < ActiveRecord::Base
  acts_as_indexed :fields => [:content]
end

Use the IndexedModels.with_query method to search every model that acts_as_indexed. You can specify which models to include or exclude using :only and :except.

IndexedModels.with_query 'michael jackson', :only => [:article, :review]

The results are returned grouped by model.

[[#<Article id:1>, #<Article id:2>], [#<Review id: 1>]]

Query Options

The following query operators are supported:

  • AND

    This is the default option. 'cat dog' will find records matching 'cat' AND 'dog'.

  • NOT

    'cat -dog' will find records matching 'cat' AND NOT 'dog'

  • INCLUDE

    'cat +me' will find records matching 'cat' and 'me', even if 'me' is smaller than the min_word_size

  • “”

    Quoted terms are matched as phrases. '“cat dog”' will find records matching the whole phrase. Quoted terms can be preceded by the NOT operator; 'cat -“big dog”' etc. Quoted terms can include words shorter than the min_word_size.

  • ^

    Terms that begin with ^ will match records that contain a word starting with the term. '^cat' will find matches containing 'cat', 'catapult', 'caterpillar' etc.

  • ^“”

    A quoted term that begins with ^ matches any phrase that begin with this phrase. '^“cat d”' will find records matching the whole phrases “cat dog” and “cat dinner”. This type of search is useful for autocomplete inputs.

Pagination

Since with_query is a named scope, WillPaginate can be used in the normal fashion.

@images = Image.with_query('girl').paginate(:page => 1, :per_page => 5)

Further Configuration

A config block can be provided in your environment files or initializers. Example showing defaults:

ActsAsIndexed.configure do |config|
  config.index_file = [RAILS_ROOT,'index']
  config.index_file_depth = 3
  config.min_word_size = 3
end

A full rundown of the available configuration options can be found in lib/acts_as_indexed/configuration.rb

RDoc Documentation

To generate the RDoc documentation, run the rake rdoc task in the acts_as_indexed plugin folder. Then point your web browser at vendor/plugins/acts_as_indexed/rdoc/index.html.

Alternatively, you can view the rdoc documentation online.

Problems, Comments, Suggestions?

All of the above are most welcome. dougal.s@gmail.com

Credits

Douglas F Shearer - douglasfshearer.com

Future Releases

Future releases will be looking to add the following features:

  • Optional html scrubbing during indexing.

  • Ranking affected by field weightings.

  • Support for DataMapper, Sequel and the various MongoDB ORMs.

  • UTF-8 support. See the current solution here:

gist.github.com/193903bb4e0d6e5debe1

Something went wrong with that request. Please try again.