ruby script/plugin install svn://rubyforge.org/var/svn/model-ac/trunk/vendor/plugins/model_auto_completer

belongs_to_auto_completer(object, association, method, options={}, tag_options={}, completion_options={})

Generates a text field that autocompletes following a belongs_to association, and a hidden field managed with JavaScript that stores the ID of the selected models.

Say we have these models:

  class Book < ActiveRecord::Base
    belongs_to :author, :class_name => 'Person', :foreign_key => 'author_id'
  end

  class Person < ActiveRecord::Base
    has_many :books

    def fullname
      "#{surname}, #{name}"
    end
  end

In the form to edit books you can just do this to assign an author:

<%= belongs_to_auto_completer :book, :author, :fullname %>

We assume here BooksController implements an action called auto_complete_belongs_to_for_book_author_fullname:

  def auto_complete_belongs_to_for_book_author_fullname
    query = params[:author][:fullname].downcase
    query = "%#{query}%"
    @authors = Person.find(
      :all,
      :conditions => ['LOWER(name) LIKE ? OR LOWER(surname) LIKE ?', query, query],
      :limit => 10
    )
    render :partial => 'book_author_completions'
  end

The name of the action can be configured using the :action option.

There is convenience class method for controllers auto_complete_belongs_to_for, which generates a default action, analogous to the one in the builtin autocompleter.

The text field is named "association[method]", in the example "author[fullname]". We don‘t include the object so that params[:book] does not contain that auxiliary value.

The hidden field is named "object[association_foreign_key]", in the example that is "book[author_id]". The goal is that regular mass-assignement idioms like Book.new(params[:book]) work as usual and are all you need to associate the author. The name of the foreign key is figured out dynamically by reflection on the association.

See the documentation of model_auto_completer to see how to send the completions back to the view. More options other than :action are available, this helper is just a convenience wrapper for that one.

model_auto_completer(tf_name, tf_value, hf_name, hf_value, options={}, tag_options={}, completion_options={})

This is the most generic helper for model autocompletion. This widget creates a text field and manages a hidden field where the ID of the selected model is stored.

The widget expects a regular unordered list of completions as you send for the standard Rails autocompleter, except list items have to come with an ID attribute. By default, any trailing integer will be considered to be the identifier of the corresponding model. For example:

  
    <% for author in @authors %>
    <%=h author.fullname %>
    <% end %>
  

There‘s a configurable regexp to extract the IDs, see below.

Autocompletion itself is delegated to the standard Rails autocompleter. By default, the name of the expected action is auto_complete_model_for_ and a suffix computed from the textfield name (tf_name). If the textfield is called owner[fullname] we obtain owner_fullname, you see how it works. The text field will initially contain tf_value.

Note that model_auto_completer itself uses the underlying callback :after_update_element to extract the model id. If you need a callback use the provided wrapper instead, which in addition receives the hidden field and the extracted model id. See options below.

The hidden field will be named hf_name and will have an initial value of hf_value.

Generated INPUT elements have a random suffix in their IDs so that you can include this widget more than once in the same page.

Available options are:

* :regexp_for_id: A regexp with at least one group. The first capture is assumed to be the ID of the corresponding model. Defaults to (\d+)$.
* :allow_free_text: If false the widget only allows values that come from autocompletion. If the user leaves the text field with a free string the text field is rolled back to the last valid value. If true free edition is allowed, and if the text field contains free text the hidden field will contain the empty string. Defauts to false.
* :send_on_return: Pressing the return key to select an item on the selection list does not submit the form in any major browser except Safari (Konqueror does not submit it either). If false, the return key is captured in Safari to prevent that, and as a side-effect the user cannot submit the form pressing the return key in the very textfield. This config value is ignored in the rest of browsers. Defaults to false.
* :after_update_element: A JavaScript function that is called when the user has selected one of the completions. It gets four arguments, the text field, the selected list item, the hidden field, and the extracted model id.
* :controller: The controller that implements the action that returns completions. Defaults to the current controller.
* :action: The action that provides the completions. The default is explained above.

There is currently no advanced documentation for this plugin.