acts_as_ferret

This ActiveRecord mixin adds full text search capabilities to any Rails model.

It is heavily based on the original acts_as_ferret plugin done by Kasper Weibel and a modified version done by Thomas Lockney, which both can be found on ferret.davebalmain.com/trac/wiki/FerretOnRails

Project URLs

Wiki: wiki.github.com/jkraemer/acts_as_ferret/ Please post issues on Lighthouse: j-k.lighthouseapp.com/projects/45560-acts-as-ferret API docs: rdoc.info/github/jkraemer/acts_as_ferret

Supported Rails versions

From version 0.5 onwards acts_as_ferret requires Rails 3. For earlier Rails versions (2.3.x, ymmv for earlier versions) please use acts_as_ferret versions 0.4.x or the rails-2.3.x branch on github.

Installation

Aaf is available as a gem (gem install acts_as_ferret), or via git from github.com. Github also offers tarball downloads, check out github.com/jkraemer/acts_as_ferret/tree/master .

Rails 3

add

gem 'acts_as_ferret', '>= 0.5'

to your Gemfile. Bundler will pull in the jk-ferret gem as a dependency, which is an ‘unofficial’ Ferret gem built by me based on Ferret’s master branch on github (the latest official ferret gem is 0.11.6 and is missing quite some bug fixes that happened since then).

After running ‘bundle install’, have bundler execute the aaf_install script:

bundle exec aaf_install

This will copy the capistrano recipe, the ferret server config and it’s startup script into your project.

In order to have the capistrano recipe loaded you’ll have to patch your Capfile a bit. I use to have a line like that in my Capfiles, loading everything found below RAILS_ROOT/lib/recipes:

Dir['lib/recipes/*/.rb'].each { |plugin| load(plugin) }

Rails 2.x

To set up your Rails project to use the acts_as_ferret gem, add this to your project’s config/environment.rb:

config.gem 'acts_as_ferret', :version => '~> 0.4.8'

With the gem installed, change into your RAILS_ROOT and run the supplied aaf_install script. This will copy rake tasks, capistrano recipes and the ferret server config and startup script into your project.

If you’re using Capistrano, patch your Capfile as described above for Rails 3.

Installation inside your Rails project via script/plugin

script/plugin install git://github.com/jkraemer/acts_as_ferret.git

No additional setup needed.

Usage

There are two ways to make your models searchable with aaf. The option to configure acts_as_ferret with a single configuration file has been introduced because it makes more sense when a single index holds multiple models - it’s simply more logicl to define that index and tell which models should go into it than to call acts_as_ferret in each model pointing to the same index every time.

central configuration file

With this option, all acts_as_ferret indexes are configured in a single file, RAILS_ROOT/config/aaf.rb:

ActsAsFerret::define_index( ‘my_index’,

:models => {
  SomeModel => {
    :fields => {
      :name => { :boost => 4, :store => :yes, :via => :ferret_title },
      :foo => { :store => :no,  :index => :untokenized },
      :baz => { :store => :yes, :via => :ferret_content }
    }
  }
} )

ActsAsFerret::define_index( ‘some_other_index’,

:models => {
  Foo => { :fields => { ... } },
  Bar => { ... },
} )

As you can see for every index you want to define there’s a single call, and each model that should go into the index gets it’s own ferret options hash (see the acts_as_ferret class method docs for all available options).

In your models (the old fashioned way)

include the following in your model class (specifiying the fields you want to get indexed):

acts_as_ferret :fields => [ :title, :description ]

now you can use ModelClass.find_with_ferret(query) to find instances of your model whose indexed fields match a given query. All query terms are required by default, but explicit OR queries are possible. This differs from the ferret default, but imho is the more often needed/expected behaviour (more query terms result in less results).

Please see ActsAsFerret::ActMethods#acts_as_ferret for more information.

Known issues

aaf is not yet ready for Rails3. Feel free to submit patches!

Rails 3 :More Like this no longer works for unsaved records (test fails in content_test.rb test_more_like_this_new_record)

Rails 3: Sorting does not work - causes failure in sorting test & pagination test.

License

Released under the MIT license.

Authors

• Kasper Weibel Nielsen-Refs (original author)

• Jens Kraemer <jk@jkraemer.net> (current maintainer)