AutocompleteRails

Easily set up Rails controller actions for use with jQuery UI's Autocomplete widget.

Please use GitHub Issues to report bugs. You can contact me directly on twitter at @JustinTomich.

AutocompleteRails is a lightweight component with easily understandable, minimal, source code. There are other autocomplete gems out there that support multiple ORMs and provide client-side javascript, at the cost of increased complexity. AutocompleteRails only supports ActiveRecord, and only provides rails controller functionality. Client side, you use jQuery UI's autocomplete widget, which you wire up yourself.

AutocompleteRails supports Rails 4 and Rails 5.

To get started, add the gem to your Rails app's Gemfile:

gem 'autocomplete_rails'

And install the gem:

bundle install

You will also need to install:

• jQuery, see the jquery-rails gem.
• jQuery UI, see the jquery-ui-rails gem.

Once the gem is installed, there are 3 steps to set up an autocomplete:

• call autocomplete in your controller
• add a route to your newly generated autocomplete method
• provision an input in your UI with jQuery UI's autocomplete widget

Any controller needing an autocomplete action should invoke class method autocomplete with the model class and method to be autocompleted as arguments. An autocomplete method is generated. Then add a route leading to your generated method.

For example, to autocomplete users by email address in a Posts controller:

class PostsController < ApplicationController
    autocomplete :user, :email
end

autocomplete :user, :email creates a method on PostsController named autocomplete_user_email.

Add a route to your autocomplete action. For the controller listed above, you might add:

resources :posts do
  get :autocomplete_user_email, on: :collection
end

jQuery UI's autocomplete widget is flexible and well documented. The most basic setup: just set the widget's source option to the autocomplete rails controller path you wish to access. A common way to do this is by setting the path to the autocomplete action in a data attribute of the input, and access it from coffeescript/javascript. For example:

Place the url in a data attribute of a text field tag:

<%= text_field_tag :search, params[:search], data: { autocomplete: autocomplete_user_email_users_path } %>

Which creates an tag that looks like this:

<input name="search" type="text" data-autocomplete="/users/autocomplete_user_email">

A simple jQuery event handler will attach autocomplete to any input[data-autocomplete]. Pass in your autocomplete url as the source to jQuery's autocomplete widget. Here's an example (using turbolinks) that adds the autocomplete widget to the input field show above:

$(document).on 'turbolinks:load', ->
  $("input[data-autocomplete]").each ->
    url = $(this).data('autocomplete')
    $(this).autocomplete
      source: url

You can read more about jQuery UI's autocomplete here:

http://api.jqueryui.com/autocomplete/

AutocompleteRails has a number of options, see controller.rb.

Call a separate method to generate the label in the response. If a label_method is not specified, it will default to the value_method.

If your label_method is not a single column in your database but is reliant on multiple columns in your model, you need to specify full_model (see below) to load all columns for your model.

Example:

class PostsController < ApplicationController
    autocomplete :user, :email, label_method: :name
end

Load the full model from the database. Default is false.

When full_model is false, only the value_method and label_method are selected from the database.

Example: your label_method is first_and_last_name, which is composed of multiple columns from your database. Load the full model to allow the method to be called:

class PostsController < ApplicationController
    autocomplete :user, :email, label_method: :full_name, full_model: true
end

Limit the number of responses. The default limit is 10.

Example, setting the limit to 5:

class PostsController < ApplicationController
    autocomplete :user, :email, limit: 5
end

If set to true, a case-sensitive search is performed. Defaults to false, performing a case-insensitive search.

class PostsController < ApplicationController
    autocomplete :user, :email, case_sensitive: true
end

Specify additional method called and returned in the response. Specify additional_data as an array.

If additional_data is specified and full_model is not specified, each additional_data column is added to the columns selected.

class PostsController < ApplicationController
    autocomplete :user, :email, additional_data: [:first_name, :last_name]
end

Build your autocomplete query from the specified ActiveRecord scope(s). Multiple scopes can be used, pass them in as an array.

class PostsController < ApplicationController
    autocomplete :user, :email, scopes: [:active_users]
end

Specify a sort order. If none is specified, defaults to 'LOWER(#{table}.#{value_method}) ASC'.

This gem was inspired by, and draws heavily from:

• autocomplete
• rails3-jquery-autocomplete
• rails4-autocomplete

This project rocks and uses MIT-LICENSE.