Installation

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:

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)