# Soulmate Rails [](http://badge.fury.io/rb/soulmate_rails) [](https://travis-ci.org/dhruvasagar/soulmate_rails) [](https://gemnasium.com/dhruvasagar/soulmate_rails)
Soulmate Rails is a rails plugin that helps to solve the common problem
building auto-completion back-end in rails intuitively. It extends the
soulmate gem Soulmate to
make it easily pluggable into a rails project.
## Getting Started
### Installation :
```sh
$ gem install soulmate_rails
```
OR add this to your `Gemfile` :
```ruby
gem 'soulmate_rails'
```
### Usage :
Following is an example of how one can use Soulmate Rails for enabling backend
autocompletion using redis.
```ruby
class User < ActiveRecord::Base
autocomplete :first_name, :score => :calculate_score
autocomplete :last_name, :score => :id
def calculate_score
100 / self.id # simple score calculator
end
end
1.9.3p385 :001 > User.create(:first_name => 'First1', :last_name => 'Last1')
1.9.3p385 :002 > User.create(:first_name => 'First2', :last_name => 'Last2')
1.9.3p385 :003 > User.create(:first_name => 'First3', :last_name => 'Last3')
1.9.3p385 :004 > User.search_by_first_name('firs')
=> [#"First1", "last_name"=>"Last1" "id"=>1},
@changed_attributes={}>, #"First2", "last_name"=>"Last2" "id"=>2},
@changed_attributes={}>, #"First3", "last_name"=>"Last3" "id"=>3},
@changed_attributes={}>]
1.9.3p385 :005 > User.search_by_last_name('last1')
=> [#"First1", "last_name"=>"Last1" "id"=>1},
@changed_attributes={}>]
1.9.3p385 :006 > User.search_by_last_name('las')
=> [#"First3", "last_name"=>"Last3" "id"=>3},
@changed_attributes={}>, #"First2", "last_name"=>"Last2" "id"=>2},
@changed_attributes={}>, #"First1", "last_name"=>"Last1" "id"=>1},
@changed_attributes={}>]
```
The `autocomplete` method takes 2 arguments :
* attribute name to use for autocompletion.
* options that determine how autocompletion works for indexing.
### Methods added by autocomplete :
* Class Methods
* `search_by(attribute, term, options={})` - Generic method to search by
an attribute for which an autocomplete was defined.
* `search_by_#{attribute}(term, options={})` - Specific methods for each
attribute autocomplete was defined for.
* Instance Methods
* `update_index_for(attribute, options={})`
* `update_index_for_#{attribute}` - used in an `after_save` callback to
update index for searching.
* `remove_index_for(attribute)`
* `remove_index_for_#{attribute}` - used in a `before_destroy` callback to
remove index for searching. Hence you should use `destroy` as opposed to
`delete` to ensure the callbacks are invoked appropriately by rails and
soulmate updates the index.
### Options you can provide to `autocomplete` :
* `:score` : This is required. Soulmate uses it for sorting the results (in
reverse order, i.e. higher score first). This can be the name of a function
or can also be the name of another attribute with integer values.
* `:aliases` : This is optional. Soulmate uses this as aliases for the term
field and uses it for searching as well. This can be an array of values or
the name of a method which returns an array of values.
* `:data` : This is optional. This can either be the name of a method which
returns data or a hash or a string. Once you perform your search using
`search_by` or `search_by_#{attribute}` it will set the value of :data
corresponding to the object to soulmate_data attr_accessor and can be
accessed by calling the soulmate_data accessor on the model object.
### Configuration :
Within your rails application inside config/application.rb you can optionally
provide redis configuration. Example :
```ruby
config.soulmate_rails.redis = 'redis://127.0.0.1:6380/0'
# or you can assign an existing instance of Redis, Redis::Namespace, etc.
# config.soulmate_rails.redis = $redis
```
Alternatively, you can also add configuration in an initializer. Example :
```ruby
Soulmate.redis = 'redis://127.0.0.1:6380/0'
# or you can assign an existing instance of Redis, Redis::Namespace, etc.
# Soulmate.redis = $redis
```
## Contributing
### Reporting an Issue :
* Use Github
Issue Tracker to report issues.
### Contributing to code :
* Fork it.
* Commit your changes ( git commit ).
* Push to github ( git push ).
* Open a Pull Request.
## License
Soulmate Rails is released under the MIT License