todototry / acts_as_ferret Goto Github PK

= 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 http://ferret.davebalmain.com/trac/wiki/FerretOnRails


== Project URLs

Wiki: http://wiki.github.com/jkraemer/acts_as_ferret/
Please post issues on Lighthouse: http://j-k.lighthouseapp.com/projects/45560-acts-as-ferret
API docs: http://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
http://github.com/jkraemer/acts_as_ferret/tree/master .


=== Rails 3

add

<tt>gem 'acts_as_ferret', '>= 0.5'</tt>

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:

<tt>bundle exec aaf_install</tt>

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:

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


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

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

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

<tt>acts_as_ferret :fields => [ :title, :description ]</tt>

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!

== License

Released under the MIT license.

== Authors

* Kasper Weibel Nielsen-Refs (original author)
* Jens Kraemer <[email protected]> (current maintainer)