instance method observe_field

Observes the field with the DOM ID specified by field_id and calls a callback when its contents have changed. The default callback is an Ajax call. By default the value of the observed field is sent as a parameter with the Ajax call.

Example:

# Generates: new Form.Element.Observer('suggest', 0.25, function(element, value) {new Ajax.Updater('suggest',
#         '/testing/find_suggestion', {asynchronous:true, evalScripts:true, parameters:'q=' + value})})
<%= observe_field :suggest, :url => { :action => :find_suggestion },
     :frequency => 0.25,
     :update => :suggest,
     :with => 'q'
     %>

Required options are either of:

:url

url_for-style options for the action to call when the field has changed.

:function

Instead of making a remote call to a URL, you can specify javascript code to be called instead. Note that the value of this option is used as the body of the javascript function, a function definition with parameters named element and value will be generated for you for example:

observe_field("glass", :frequency => 1, :function => "alert('Element changed')")

will generate:

new Form.Element.Observer('glass', 1, function(element, value) {alert('Element changed')})

The element parameter is the DOM element being observed, and the value is its value at the time the observer is triggered.

Additional options are:

:frequency

The frequency (in seconds) at which changes to this field will be detected. Not setting this option at all or to a value equal to or less than zero will use event based observation instead of time based observation.

:update

Specifies the DOM ID of the element whose innerHTML should be updated with the XMLHttpRequest response text.

:with

A JavaScript expression specifying the parameters for the XMLHttpRequest. The default is to send the key and value of the observed field. Any custom expressions should return a valid URL query string. The value of the field is stored in the JavaScript variable value.

Examples

:with => "'my_custom_key=' + value"
:with => "'person[name]=' + prompt('New name')"
:with => "Form.Element.serialize('other-field')"

Finally

:with => 'name'

is shorthand for

:with => "'name=' + value"

This essentially just changes the key of the parameter.

:on

Specifies which event handler to observe. By default, it’s set to “changed” for text fields and areas and “click” for radio buttons and checkboxes. With this, you can specify it instead to be “blur” or “focus” or any other event.

Additionally, you may specify any of the options documented in the Common options section at the top of this document.

Example:

# Sends params: {:title => 'Title of the book'} when the book_title input
# field is changed.
observe_field 'book_title',
  :url => 'http://example.com/books/edit/1',
  :with => 'title'

# Sends params: {:book_title => 'Title of the book'} when the focus leaves
# the input field.
observe_field 'book_title',
  :url => 'http://example.com/books/edit/1',
  :on => 'blur'