bootstrap3_autocomplete_input

Autocomplete/typeahead input ready to be used with Bootstrap 3 in Rails 4.

For Bootstrap 4 and Rails 5 - use gem bootstrap 4 autocomplete input.

Features:

• Works with SimpleForm.
• Adds an input with autocomplete/typeahead compatible with Bootstrap 3.

The gem uses the autocomplete library from Bootstrap-3-Typeahead that works with Bootstrap 3. With Twitter Bootstrap 3 the typeahead plugin had been dropped in favor to Twitter's' typeahead.js library. Twitter's typeahead doesn't work with Bootstrap 3 directly. For using autocomplete with jQuery autocomplete library in Rails 4, see the gem rails4-autocomplete.

Install

Gemfile

gem 'simple_form'
gem 'bootstrap3_autocomplete_input'

It assumes that you have Bootstrap 3 in your application. For example, you can use the bootstrap-sass gem.

gem 'jquery-rails'
gem 'jquery-ui-rails'
gem 'sass-rails', '>= 3.2'
gem 'bootstrap-sass', '~> 3.3.1'

Javascript

Include js files (bootstrap3-typeahead.min, bootstrap3-autocomplete-input.min) in your assets file 'app/assets/javascripts/application.js' after 'bootstrap.js'.

//= require jquery2
//= require jquery_ujs
//= require bootstrap
//= require bootstrap3-typeahead.min
//= require bootstrap3-autocomplete-input
//= require bootstrap3-autocomplete-input-init

for Turbolinks:

//= require jquery2
//= require jquery_ujs
//= require bootstrap
//= require bootstrap3-typeahead.min
//= require bootstrap3-autocomplete-input
//= require bootstrap3-autocomplete-input-init-turbolinks

CSS

All CSS for autocomplete input is already contained in Bootstrap 3 CSS.

For example, if you use bootstrap-sass, your css files 'app/assets/stylesheets/application.css.scss' might be like

@import "bootstrap-sprockets";
@import "bootstrap";

Usage

Assuming that we have models Order and Client.

class Order < ActiveRecord::Base
  belongs_to :client

end

class Client < ActiveRecord::Base
  has_many :orders

end

We will add autocomplete input to order's form for editing its client.

controller

class ClientsController < ApplicationController
   autocomplete :client, :name
   ...
end

This will generate the controller method 'autocomplete_client_name' that returns JSON data with clients.

routes

Add routes for the generated controller action:

resources :clients do
  get :autocomplete_client_name, :on => :collection
end
    

This will generate route with name autocomplete_client_name_clients which can be accesedby path autocomplete_client_name_clients_path.

model

specify what to display as a value in a text field:

class Client < ActiveRecord::Base
	belongs_to :order

	def to_s
		name
	end
end

view

simple_form

use :autocomplete input type for the client's field in 'app/views/orders/_form.html.haml'

=simple_form_for @order do |f|
    = f.error_notification

    = f.input :field1
    
    = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url

    = f.button :submit, 'Save', :class=> 'btn-primary'

Controller

The gem has method "autocomplete" to generate an action in your controller:

class ClientsController < ApplicationController

  autocomplete :client, :name

This will add new action 'autocomplete_client_name' where :client is the model class name and :name is the field name in the model. The action uses params[:q] for the searching term and queries the database.

The action returns data in JSON format:

[["id1", "name1"], ["id2", "name2"], ..]

which is an array of ids and titles.

Options for controller method

class ClientsController < ApplicationController

  autocomplete :client, :name, { options_hash_here }

class_name

column_name

class ClientsController < ApplicationController

  autocomplete :client, :name, { :column_name => 'title_long' }

It will search in this column in database.

extra_columns

class ClientsController < ApplicationController

  autocomplete :client, :name, { extra_columns: [:lastname, :birthdate], column_name: 'fullname' }

display_id

• Method used for getting ID of the record.
• Make sure that columns this method depends on are included in :extra_columns option.

display_value

class ClientsController < ApplicationController

  autocomplete :client, :name, { :display_value => 'fullname', :full_model=>true }
  ...
end

where, where_method

Additional WHERE conditions

• Add additional filter using :scopes option

autocomplete :client, :name, { :scopes => [:w_usa, :w_active]}

# define scopes in model
class Client < ActiveRecord::Base
  ...
  # scopes
  scope :w_usa, -> { where(region_id: 1) }
  scope :w_active, -> { where(active: true) }
  
end

• Add additional filter using :where option with search condition

autocomplete :client, :name, { :where => 'region_id=1' }

• For dynamic search conditions use :where_method option

class ClientsController < ApplicationController
    autocomplete :client, :name, { :where_method => :w_region }
    
    ...
    
    def w_region
        # get value from params
        v = params[:region_id]
        
        if v
           return "region_id=#{v}"
        end
         
        nil 
    end
end    
    

model

class Client < ActiveRecord::Base

def name_with_birthdate firstname+', '+birthdate end end

It will display search results using this method. You must set option :full_model=>true if you search by one column but you want to display value from other columns.

```ruby
# JSON data returned by the controller
[[1, 'Mark Twen, 1980'], [2, 'John Deer, 1985'], ..]

Options for input

specify options:

= simple_form_for @order do |f|

  = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url, :option_name => opt_value, :option_name2=>value2

Data source

You have several options to get data for search:

• :source => url - get static data downloaded from URL
• :source_query => url - query data with a keyword from URL
• :source_array => array - data is stored in local array of strings

examples:

  = f.input :client, :as => :autocomplete, :source => autocomplete_client_name_clients_url
  
  = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url
  
  = f.input :client, :as => :autocomplete, :source_array => ['item1', 'item2', ..]

Object id

Autocomplete input adds a hidden field to use the id of the selected item. Unless you use local array as data source (:source_array), the hidden field for the id is added automatically.

  = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url

This will generate HTML like

<input id="order_client_id" type="hidden" value="0" name="order[client_id]">

<input id="order_client" name="order[client]"
class="autocomplete optional" type="text" value="*some value*" 
data-source-query="http://localhost:3000/clients/autocomplete_client_name" data-provide="typeahead" data-field-id="order_client_id" 
autocomplete="off">

This will update the field with id "order_client_id" with the id of the selected object.

Data posted from the form to the server will contain the id of the selected client (params[:order][:client_id])

params[:order]

{
client_id: 5,
client: 'client name',
...
}

If you don't want to have a hidden field for object id, set :field_id option to false:

  = f.input :client, :as => :autocomplete, :source => autocomplete_client_name_clients_url, :field_id=>false

This will generate HTML without a hidden field:

<input id="order_client" name="order[client]"
class="autocomplete optional" type="text" value="*value*" 
data-source="http://localhost:3000/clients/autocomplete_client_name" 
data-provide="typeahead" 
autocomplete="off">

:items

The max number of items to display in the dropdown. Default is 8.

= simple_form_for @order do |f|

  = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url, :items => 2

:minLength

The minimum character length needed before triggering autocomplete suggestions. You can set it to 0 so suggestion are shown even when there is no text when lookup function is called. Default is 1.

= simple_form_for @order do |f|

  = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url, :minLength=>3

View the full list of options at https://github.com/bassjobsen/Bootstrap-3-Typeahead. Note that not all options from that list are supported by the current gem.

afterSelect

The callback function to be execute after an item is selected.

= simple_form_for @order do |f|

  = f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url, :minLength=>3, :afterSelect=>'after_select_client'




:javascript
  function after_select_client(item){
    console.log('item is selected');
    console.log(item);

  }

Examples

Static data from the server

= simple_form_for @order, html: { autocomplete: 'off' } do |f|
  -#.. other fields..
  
  = f.input :client, :as => :autocomplete, :source => autocomplete_client_name_clients_url
  

Data will be loaded from the server once after page loads, and all queries to search a string will be against the stored data. Do not use this if you have a big number of items for client.

Query data from the server

= f.input :client, :as => :autocomplete, :source_query => autocomplete_client_name_clients_url

Data will loaded from the server every time you type a new string in the field.

Search by name, display full name in search result

class ClientsController < ApplicationController

  autocomplete :client, :name, { :display_value => 'name_with_birthdate', :full_model=>true }
  ...
end


# model

class Client < ActiveRecord::Base

  def name_with_birthdate
    firstname+', '+birthdate
  end
end

Tests

Development

This gem uses the ORM library for ActiveRecord models included in rails3-jquery-autocomplete

TODO

Write tests