Project Moved

There has been some confusion around the naming as to where to find the Rails4 version of this gem due to the original naming. With the latest release I have taken the opportunity to address this by moving the official repo.

The official repo is now located at rails-jquery-autocomplete

rails3-jquery-autocomplete

An easy way to use jQuery's autocomplete with Rails 3.

Supports both ActiveRecord, mongoid, and MongoMapper.

Works with Formtastic and SimpleForm

ActiveRecord

You can find a detailed example on how to use this gem with ActiveRecord here.

MongoID

You can find a detailed example on how to use this gem with MongoID here. (Same thing, different branch)

Before you start

Make sure your project is using jQuery-UI and the autocomplete widget before you continue.

You can find more info about that here:

• http://jquery.com/
• http://jqueryui.com/demos/autocomplete/
• http://github.com/rails/jquery-ujs

I'd encourage you to understand how to use those 3 amazing tools before attempting to use this gem.

Installing

Include the gem on your Gemfile

gem 'rails3-jquery-autocomplete'

Install it

bundle install

Rails 3.0.x

Run the generator

rails generate autocomplete:install

And include autocomplete-rails.js on your layouts

javascript_include_tag "autocomplete-rails.js"

Upgrading from older versions

If you are upgrading from a previous version, run the generator after installing to replace the javascript file.

rails generate autocomplete:install

I'd recommend you do this every time you update to make sure you have the latest JS file.

Uncompressed Javascript file

If you want to make changes to the JS file, you can install the uncompressed version by running:

rails generate autocomplete:uncompressed

Rails 3.1.x and higher

Just add it to your app/assets/javascripts/application.js file

//= require jquery
//= require jquery_ujs
//= require jquery-ui
//= require autocomplete-rails

Usage

Model Example

Assuming you have a Brand model:

class Brand < ActiveRecord::Base
end

create_table :brand do |t|
  t.column :name, :string
end

Controller

To set up the required action on your controller, all you have to do is call it with the class name and the method as in the following example:

class ProductsController < Admin::BaseController
  autocomplete :brand, :name
end

This will create an action autocomplete_brand_name on your controller, don't forget to add it on your routes file

resources :products do
  get :autocomplete_brand_name, :on => :collection
end

Options

:full => true

By default, the search starts from the beginning of the string you're searching for. If you want to do a full search, set the full parameter to true.

class ProductsController < Admin::BaseController
  autocomplete :brand, :name, :full => true
end

The following terms would match the query 'un':

• Luna
• Unacceptable
• Rerun

:full => false (default behavior)

Only the following terms mould match the query 'un':

• Unacceptable

:limit => 10 (default behavior)

By default your search result set is limited to the first 10 records. This can be overridden by specifying the limit option.

:extra_data

By default, your search will only return the required columns from the database needed to populate your form, namely id and the column you are searching (name, in the above example).

Passing an array of attributes/column names to this option will fetch and return the specified data.

class ProductsController < Admin::BaseController
  autocomplete :brand, :name, :extra_data => [:slogan]
end

:display_value

If you want to display a different version of what you're looking for, you can use the :display_value option.

This options receives a method name as the parameter, and that method will be called on the instance when displaying the results.

class Brand < ActiveRecord::Base
  def funky_method
    "#{self.name}.camelize"
  end
end


class ProductsController < Admin::BaseController
  autocomplete :brand, :name, :display_value => :funky_method
end

In the example above, you will search by name, but the autocomplete list will display the result of funky_method

This wouldn't really make much sense unless you use it with the "id_element" attribute. (See below)

Only the object's id and the column you are searching on will be returned in JSON, so if your display_value method requires another parameter, make sure to fetch it with the :extra_data option

:hstore

Added option to support searching in hstore columns.

Pass a hash with two keys: :method and :key with values: the hstore field name and the key of the hstore to search.

e.g autocomplete :feature, :name, :hstore => {:method => 'name_translations', :key => 'en'}

:scopes

Added option to use scopes. Pass scopes in an array. e.g :scopes => [:scope1, :scope2]

:column_name

By default autocomplete uses method name as column name. Now it can be specified using column_name options :column_name => 'name'

json encoder

Autocomplete uses Yajl as JSON encoder/decoder, but you can specify your own

class ProductsController < Admin::BaseController
  autocomplete :brand, :name do |items|
     CustomJSON::Encoder.encode(items)
  end
end

View

On your view, all you have to do is include the attribute autocomplete on the text field using the url to the autocomplete action as the value.

form_for @product do |f|
  f.autocomplete_field :brand_name, autocomplete_brand_name_products_path
end

This will generate an HTML tag that looks like:

<input type="text" data-autocomplete="products/autocomplete_brand_name">

If you are not using a FormBuilder (form_for) or you just want to include an autocomplete field without the form, you can use the autocomplete_field_tag helper.

form_tag 'some/path'
  autocomplete_field_tag 'address', '', address_autocomplete_path, :size => 75
end

Multiple Values Separated by Delimiter

To generate an autocomplete input field that accepts multiple values separated by a given delimiter, add the 'data-delimiter' and :multiple options:

form_for @product do |f|
  f.autocomplete_field :brand_names, autocomplete_brand_name_products_path,
  'data-delimiter' => ',', :multiple => true
end

NOTE: Setting the :multiple option to true will result in the chosen values being submitted as an array. Leaving this option off will result in the values being passed as a single string, with the values separated by your chosen delimiter.

Automatically focus on the first autocompleted item

To have the first item be automatically focused on when the autocomplete menu is shown, add the 'data-auto-focus' option and set it to true.

form_for @product do |f|
	f.autocomplete_field :brand_names, autocomplete_brand_name_products_path,
	'data-auto-focus' => true
end

Now your autocomplete code is unobtrusive, Rails 3 style.

Getting the object id

If you need to use the id of the selected object, you can use the id_element attribute too:

f.autocomplete_field :brand_name, autocomplete_brand_name_products_path, :id_element => '#some_element'

This will update the field with id *#some_element with the id of the selected object. The value for this option can be any jQuery selector.

Changing destination element

If you need to change destination element where the autocomplete box will be appended to, you can use the :append_to option which generates a data-append-to HTML attribute that is used in jQuery autocomplete as append_to attribute.

The :append_to option accepts a string containing jQuery selector for destination element:

f.autocomplete_field :product_name, '/products/autocomplete_product_name', :append_to => "#product_modal"

The previous example would append the autocomplete box containing suggestions to element jQuery('#product_modal'). This is very useful on page where you use various z-indexes and you need to append the box to the topmost element, for example using modal window.

Sending extra search fields

If you want to send extra fields from your form to the search action, you can use the :fields options which generates a data-autocomplete-fields HTML attribute.

The :fields option accepts a hash where the keys represent the Ajax request parameter name and the values represent the jQuery selectors to retrieve the form elements to get the values:

f.autocomplete_field :product_name, '/products/autocomplete_product_name', :fields => {:brand_id => '#brand_element', :country => '#country_element'}

class ProductsController < Admin::BaseController
  def autocomplete_product_name
    term = params[:term]
    brand_id = params[:brand_id]
    country = params[:country]
    products = Product.where('brand = ? AND country = ? AND name LIKE ?', brand_id, country, "%#{term}%").order(:name).all
    render :json => products.map { |product| {:id => product.id, :label => product.name, :v