Module | AutoCompleteMacrosHelper |
In: |
vendor/plugins/auto_complete/lib/auto_complete_macros_helper.rb
|
Adds AJAX autocomplete functionality to the text input field with the DOM ID specified by field_id.
This function expects that the called action returns an HTML <ul> list, or nothing if no entries should be displayed for autocompletion.
You‘ll probably want to turn the browser‘s built-in autocompletion off, so be sure to include an autocomplete="off" attribute with your text input field.
The autocompleter object is assigned to a Javascript variable named field_id_auto_completer. This object is useful if you for example want to trigger the auto-complete suggestions through other means than user input (for that specific case, call the activate method on that object).
Required options are:
:url: | URL to call for autocompletion results in url_for format. |
Addtional options are:
:update: | Specifies the DOM ID of the element whose innerHTML should be updated with the autocomplete entries returned by the AJAX request. Defaults to field_id + ‘_auto_complete‘ |
:with: | A JavaScript expression specifying the parameters for the XMLHttpRequest. This defaults to ‘fieldname=value’. |
:frequency: | Determines the time to wait after the last keystroke for the AJAX request to be initiated. |
:indicator: | Specifies the DOM ID of an element which will be displayed while autocomplete is running. |
:tokens: | A string or an array of strings containing separator tokens for tokenized incremental autocompletion. Example: :tokens => ’,’ would allow multiple autocompletion entries, separated by commas. |
:min_chars: | The minimum number of characters that should be in the input field before an Ajax call is made to the server. |
:on_hide: | A Javascript expression that is called when the autocompletion div is hidden. The expression should take two variables: element and update. Element is a DOM element for the field, update is a DOM element for the div from which the innerHTML is replaced. |
:on_show: | Like on_hide, only now the expression is called then the div is shown. |
:after_update_element: | A Javascript expression that is called when the user has selected one of the proposed values. The expression should take two variables: element and value. Element is a DOM element for the field, value is the value selected by the user. |
:select: | Pick the class of the element from which the value for insertion should be extracted. If this is not specified, the entire element is used. |
:method: | Specifies the HTTP verb to use when the autocompletion request is made. Defaults to POST. |
# File vendor/plugins/auto_complete/lib/auto_complete_macros_helper.rb, line 58 58: def auto_complete_field(field_id, options = {}) 59: function = "var #{field_id}_auto_completer = new Ajax.Autocompleter(" 60: function << "'#{field_id}', " 61: function << "'" + (options[:update] || "#{field_id}_auto_complete") + "', " 62: function << "'#{url_for(options[:url])}'" 63: 64: js_options = {} 65: js_options[:tokens] = array_or_string_for_javascript(options[:tokens]) if options[:tokens] 66: js_options[:callback] = "function(element, value) { return #{options[:with]} }" if options[:with] 67: js_options[:indicator] = "'#{options[:indicator]}'" if options[:indicator] 68: js_options[:select] = "'#{options[:select]}'" if options[:select] 69: js_options[:paramName] = "'#{options[:param_name]}'" if options[:param_name] 70: js_options[:frequency] = "#{options[:frequency]}" if options[:frequency] 71: js_options[:method] = "'#{options[:method].to_s}'" if options[:method] 72: 73: { :after_update_element => :afterUpdateElement, 74: :on_show => :onShow, :on_hide => :onHide, :min_chars => :minChars }.each do |k,v| 75: js_options[v] = options[k] if options[k] 76: end 77: 78: function << (', ' + options_for_javascript(js_options) + ')') 79: 80: javascript_tag(function) 81: end
Use this method in your view to generate a return for the AJAX autocomplete requests.
Example action:
def auto_complete_for_item_title @items = Item.find(:all, :conditions => [ 'LOWER(description) LIKE ?', '%' + request.raw_post.downcase + '%' ]) render :inline => "<%= auto_complete_result(@items, 'description') %>" end
The auto_complete_result can of course also be called from a view belonging to the auto_complete action if you need to decorate it further.
# File vendor/plugins/auto_complete/lib/auto_complete_macros_helper.rb, line 96 96: def auto_complete_result(entries, field, phrase = nil) 97: return unless entries 98: items = entries.map { |entry| content_tag("li", phrase ? highlight(entry[field], phrase) : h(entry[field])) } 99: content_tag("ul", items.uniq) 100: end
Wrapper for text_field with added AJAX autocompletion functionality.
In your controller, you‘ll need to define an action called auto_complete_for to respond the AJAX calls,
# File vendor/plugins/auto_complete/lib/auto_complete_macros_helper.rb, line 107 107: def text_field_with_auto_complete(object, method, tag_options = {}, completion_options = {}) 108: (completion_options[:skip_style] ? "" : auto_complete_stylesheet) + 109: text_field(object, method, tag_options) + 110: content_tag("div", "", :id => "#{object}_#{method}_auto_complete", :class => "auto_complete") + 111: auto_complete_field("#{object}_#{method}", { :url => { :action => "auto_complete_for_#{object}_#{method}" } }.update(completion_options)) 112: end