AutoAwesomplete
Gem provide API (scripts, helpers, controller and base class for ajax-search) for initialize ajax awesomplete elements.
The AutoAwesomplete
based on awesomplete gem.
Installation
First
Install awesomplete and include javascript and stylesheet assets.
Second
Add this line to your application's Gemfile:
gem 'auto_awesomplete'
And then execute:
$ bundle
Third
Select one of ways to include js in pipeline. Ways described below in section Javascript include variants
Fourth
Check controller and route collation. Gem contain controller AutoAwesompletesController
and route
get 'auto_awesompletes/:class_name'
Fifth
Prepare folder app/awesomplete_search_adapters
. This folder needed for storage custom SearchAdapter
.
Compatibility
Gem tested and works in Rails 3.2 (with manual install awesomplete assets) and Rails 4.0. You can test compatibility with other versions by yourself.
Easiest way to use
Use AutoAwesomplete2Tag. It provide helper:
- awesomplete_ajax_tag
and you can define ajax awesomplete element like any other view elements in rails.
Example
(stub)
Usage
Javascript include variants
You have two ways to include javascript files. First: in gem presents helper method
- ajax_awesomplete_init_script
These helpers call javascript_include_tag
and it is useful for initialize awesomplete
scripts on a single page. Example of usage in a view:
- ajax_awesomplete_init_script
= ajax_awesomplete_tag :my_select, my_options_for_awesomplete, class: 'small'
Second variant: include files in javascript assets. For this add the
following to your app/assets/javascripts/application.js
:
//= require auto_awesomplete/ajax
Ajax awesomplete usage
For initialize ajax awesomplete you must set auto-ajax-awesomplete
css-class for input element.
Then you have two ways. Easy way for simple selection: specify default_class_name
, default_text_column
and
default_id_column
as params for :data-awesomplete-href
Other way for custom selection: create SearchAdapter
. This adapter has following requirements:
- class must be inherited from
AutoAwesomplete::SearchAdapter::Base
- file must be put in autoload folder (
app/awesomplete_search_adapter
for example) - name of a adapter class must end with
SearchAdapter
- must has function
search_default(term, page, options)
(description of the function and return value goes below)
Returned value of search_default
function must return Array as json
TIP: in search_default
you can use functions from AutoAwesomplete::SearchAdapter::Base
Finally input must has :data-awesomplete-href
attribute. This
parameter specify url for ajax load select options. You can use helper
auto_awesompletes_path(class_name: :my_class_name)
or
auto_awesompletes_path(default_class_name: my_class,
default_text_column: :name,
default_id_column: :id)
Example of minimalistic SearchAdapter
class SystemRoleSearchAdapter < AutoAwesomplete::SearchAdapter::Base
class << self
def search_default(term, page, options)
roles = default_finder(SystemRole, term, page: page).pluck(:name)
end
end
end
More about SearchAdapter
SearchAdapter
has some additional functions. First, you can define multiple search
functions in one adapter. For example in adapter for User you want to find among all
users, find users only in one department and so on. For this purpose define methods like
def search_unusual_case(term, page, options)
# must has same behavior as search_default
end
near the search_default
in SearchAdapter
. Requirement for non-default search methods:
- it must has same behavior as search_default
- name of methods must start with
search_
For use custom searcher specify it into :data-awesomplete-href
attribute:
auto_awesompletes_path(class_name: MyClassName, search_method: :unusual_case)
Contributing
- Fork it ( http://github.com/Tab10id/auto_awesomplete/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request