Module AutoCompleteMacrosHelper
In: vendor/plugins/auto_complete/lib/auto_complete_macros_helper.rb

Methods

Public Instance methods

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.

[Source]

    # 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.

[Source]

     # 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,

[Source]

     # 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

[Validate]