Painless JavaScript Using Prototype

Handling Forms

The Form and Field objects provide a number of simple but convenient functions for working with forms and input fields, as well as code that supports Prototype's AJAX implementation.

The Form Object

Generally, methods of the Form object take either an ID or an object reference to an element:

// disables the form making all elements read only  
Form.disable(form)  
// enables a form again  
Form.enable(form)  
// clears values from all form elements    
Form.reset(form)  
// returns an array of all form fields in the form  
Form.getElements(form)  
// focuses on the first form field  
Form.focusFirstElement(form)

The Field Object

The Field object deals with individual form elements, and its methods typically take an ID or an object reference to the element in a similar way to the Form object:

// clears the field, will accept any number of arguments  
Field.clear(field)  
// returns true if all given fields have a value  
Field.clear(field, anotherField)  
// gives focus to the field  
Field.focus(field)  
// selects any text in the field  
Field.select(field)

Form Serialisation

In Prototype terms, serializing a form means reading all the form's elements and turning them into a URL-encoded string (nearly) identical to the one that would be sent if you submitted the form. For example, consider this form:

<form id="search" action="search.php" method="post">  
 <input type="text" name="query" value="thing" />  
 <select name="field">  
   <option value="artistname">Artist Name</option>  
   <option value="title" selected="selected">Title</option>  
 </select>  
 <input type="submit" name="submit" value="Search" />  
</form>  
 
// query=thing&field=title&submit=Search  
Form.serialize($("search"))

Notice that Form.serialize cleverly smoothes over the differences between the ways in which different form elements are accessed, so that inputs, selects, checkboxes and radio buttons are handled properly. Form.serialize is useful for several tasks, but comes into its own when we're working with AJAX, as we'll see shortly.

Form.serialize exhibits some strange behaviour that's worth mentioning here. You'll remember that I said the URL-encoded string that Form.serialize produces is nearly identical to the one that would be sent if you submitted the form. Well, it's "nearly identical" because Form.serialize doesn't deal with submit button or image inputs properly. It includes all submit buttons in the string, regardless of whether or not they've been pressed, and completely ignores image and button inputs. As long as you're aware of this, you can code around it.

Form Observers

Form.Observer and Form.Element.Observer allow you to watch a form (or, in the latter case, a single form element) and trigger callbacks when the data changes. There are actually two flavours of each observer that check for value changes. The first is a periodic observer, which works like this:

new Form.Observer($("myform"), 1, myCallBackFunction);  
new Form.Element.Observer($("myfield"), 1, myCallBackFunction);

These observers check every second whether or not the data has changed and, if it has, will call myCallBackFunction.

The second type of observer is event-based and will only perform the check when change or click events are produced for the elements. You can use it like this:

new Form.EventObserver($("myform"), myCallBackFunction);  
new Form.Element.EventObserver($("myfield", myCallbackFunction);

If all the fields in the form you're observing support an event handler, this is a much more efficient way to observe the form. However, if you want to watch for changes in elements that don't support these events, use the periodic observers.

Working the DOM

Prototype has 4 objects (Element, Insertion, Observer, and Position) that allow various forms of DOM manipulation and smooth over many of the browser differences that make dealing with the DOM so screen-smashingly infuriating. Instead of throwing your computer out the window, have a look through this section.

The Element Object

The Element object works in the way you've probably come to expect by this point: most of Element's methods simply take an ID or an object reference to the element you want to manipulate. Here's a peek at some of the most useful methods:

// Hides an element  
Element.hide(element)  
// Shows an element  
Element.show(element)  
// Adds a CSS class to the element  
Element.addClassName(element, "cssClassName")  
// Removes a CSS class from the element  
Element.removeClassName(element, "cssClassName")  
// Returns true if element has the CSS class  
Element.hasClassName(element, "cssClassName")  
// {width: 394, height: 20}  
Element.getDimensions(element)  
// replaces the innerHTML of element with newHtml  
Element.update(element, newHtml)

See the full list at Sergio Pereira's site.

The Insertion Object

I know what you're thinking: this sounds a bit weird, right? Well, the Insertion object adds chunks of HTML in and around an element. There are 4 types of insertion: Before, After, Top and Bottom. Here's how you'd add some HTML before an element with the ID "myelement":

new Insertion.Before("myelement", "<p>I'm before!</p>");

This diagram shows where each type of Insertion will drop your HTML content in relation to the given element.

The Position Object

The Position object offers a load of methods that can tell you about a given location on the screen, and provide information about that location relative to other elements, in a cross-browser compatible way. This should take much of the fiddliness out of writing animations, effects and drag-and-drop code. Have a look at the Position reference for more details.