Section 3.6. Form Observers

3.6. Form Observers

Ajax? Why thus uncalled wouldst thou go forth?

Sophocles

The observe_field helper allows you to attach behavior to a field so that whenever it's changed, the server is notified via Ajax. It can be used like this:

<p>Text to reverse: <%= text_field_tag 'textToReverse' %></p> <span ></span></p> <%= observe_field 'text_to_reverse',      :update => 'reversed',      :url    => { :action => 'reverse' },      :with   => 'text_to_reverse' %>

Notice that this works somewhat differently than the helpers we've seen so far. The other helpers we've looked at all output HTML (e.g., links, form tags). In this example, the form field is created by text_field_tagso what does observe_field create? It creates JavaScript:

new Form.Element.EventObserver('textToReverse',   function(element, value) {     new Ajax.Updater('reversed', '/chapter3/reverse',       { parameters:'text_to_reverse=' + value });   } )

This JavaScript creates a new instance of Prototype's Form.Element.EventObserver class, bound to the text_to_reverse field. Whenever the field changes, the observer triggers Ajax.Updater, which we're familiar with from Chapter 2. For a full description of Form.Element.EventObserver, see Chapter 10.

The options available for observe_field are the same as link_to_remote (:update, :url, callbacks, etc.), with a few additions. First, the :with option is a JavaScript expression that's evaluated to determine the parameters that are passed to the server. By default it is valuewhich, when evaluated in the JavaScript context, represents the value of the field being observed. So if no :with option is provided, the generated JavaScript would look like this:

new Form.Element.EventObserver('textToReverse',   function(element, value) {     new Ajax.Updater('reversed', '/chapter3/reverse',       {parameters:value});   } }

The problem here is that the parameter isn't given a name, so won't be available in the params object on the server side. The :with option gives the parameter a name. If :with is set to foo, the code becomes:

new Form.Element.EventObserver('textToReverse',   function(element, value) {     new Ajax.Updater('reversed', '/chapter3/reverse',       {parameters:'foo='+value});   } }

But it's not quite that simple, because the helper performs one bit of magic on the :with option. If :with doesn't contain an equal sign character (=), it's interpreted as a name for the parameterso foo becomes 'foo='+value. But if :with does contain an equal sign, it remains untouchedso foo=bar remains foo=bar. In this case, rather than submitting the current value of the text field, the observer submits a constant value ("bar") as the value of foo. That could be useful, but in this case, it's not what we want.

The :frequency option allows you to specify (in seconds) how often the callback will fire. Leaving this blank (or set to zero) uses event-based observationthat is, the callback will be tied to the field's onChange event. Note that onChange is not triggered when a key is pressed, but when the field loses focus (e.g., the user tabs to the next field or clicks elsewhere). So if you want the callback to fire while the user is still changing the field (e.g., in a "live search" feature), it's best to provide a low value for :frequency, such as 0.5 to check for changes every half second.

Instead of specifying a :url option, you can also use the :function option, and provide a JavaScript snippet that will be evaluated when the field changes. For example, with :function => "alert(value)", the value of the field will be alerted whenever the observer is triggered.

3.6.1. Observing an Entire Form

observe_field's big brother is observe_formit works just the same, but it works on a whole form instead of a single field:

<form >   <p>Text to reverse: <%= text_field_tag 'text_to_reverse' %></p>   <p ></p> </form> <%= observe_form 'myForm',       :update => "reversed",       :url    => { :action => 'reverse' } %>

This observe_form helper creates an observer for the form with the ID myForm, so that whenever any of its fields change, an Ajax.Updater call is created accordingly, which passes the serialized form values to the server. The options are just the same as those on observe_field. See Chapter 10 for a full reference to Form.EventObserver.

new Form.EventObserver('myForm',   function(element, value) {     new Ajax.Updater('reversed', '/chapter3/reverse',       {parameters:value});   } )