0.01
Repository is archived
No commit activity in last 3 years
No release in over 3 years
Soulmate Rails is a tool to help solve the common problem of developing a fast autocomplete feature for Rails. It uses Redis's sorted sets to build an index of partial words and corresponding top matches. Modified by Jim Zhan to add utility functions and for bug fixing.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

>= 1.7.7
>= 2.0
 Project Readme

Soulmate Rails Gem Version Build Status Dependency Status

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 :

$ gem install soulmate_rails

OR add this to your Gemfile :

gem 'soulmate_rails'

Usage :

Following is an example of how one can use Soulmate Rails for enabling backend autocompletion using redis.

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')
  => [#<User:0x000000014bb1e8 @new_record=false,
  @attributes={"first_name"=>"First1", "last_name"=>"Last1" "id"=>1},
  @changed_attributes={}>, #<User:0x000000014bb1e9 @new_record=false,
  @attributes={"first_name"=>"First2", "last_name"=>"Last2" "id"=>2},
  @changed_attributes={}>, #<User:0x000000014bb1ea @new_record=false,
  @attributes={"first_name"=>"First3", "last_name"=>"Last3" "id"=>3},
  @changed_attributes={}>]
1.9.3p385 :005 > User.search_by_last_name('last1')
  => [#<User:0x000000014bb1e8 @new_record=false,
  @attributes={"first_name"=>"First1", "last_name"=>"Last1" "id"=>1},
  @changed_attributes={}>]
1.9.3p385 :006 > User.search_by_last_name('las')
  => [#<User:0x000000014bb1e8 @new_record=false,
  @attributes={"first_name"=>"First3", "last_name"=>"Last3" "id"=>3},
  @changed_attributes={}>, #<User:0x000000014bb1e9 @new_record=false,
  @attributes={"first_name"=>"First2", "last_name"=>"Last2" "id"=>2},
  @changed_attributes={}>, #<User:0x000000014bb1ea @new_record=false,
  @attributes={"first_name"=>"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 :

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 :

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 :

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