Prototype.js : Form

This is the first post of many about the Prototype AJAX library. For me it fills the same void that commons-lang fills in Java, which is that it includes functions to perform the common tasks that you seem to do over and over again. In this post I will cover the Form object, and all of it's methods. This post, and all posts about the Prototype library will be broken down into two sections, a summary of the API followed by detailed descriptions and examples of each function.

API Summary

void Form.disable(form)
void Form.enable(form)
void Form.focusFirstElement(form)
HTMLElement[] Form.getElements(form)
HTMLInputElement[] Form.getInputs(form, typeName, name)
void Form.reset(form)
String Form.serialize(form)

API Details

Form.disable(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Given a form ID or reference to a form element, will disable all fields, which will make them appear as greyed out.

Form.disable('theForm');
Form.disable(formRefVar);

Form.enable(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Given a form ID or reference to a form element, will enable all fields.

Form.disable('theForm');
Form.disable(formRefVar);

Form.focusFirstElement(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Places focus on the first field of the specified form. This is useful when, for example, you have a login page and you want to save the user an extra click by putting the focus on the username field so that the user can immediate start typing. This would typically be triggered in an initialization function triggered by a document onload event.

Form.focusFirstElement('theForm');
Form.focusFirstElement(formRefVar);

Form.getElements(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
An array of HTMLElement DOM objects.

Given a form ID or reference to a form element, will return a list of form field DOM obejcts. Note that there is no guarantee that the fields returned will be in the same order that they are on the page.

var fields = Form.getElements('theForm');
var fields2 = Form.getElements(formRefVar);

Form.getInputs(form, typeName, name)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.
typeName - Filter for specific input type, null or an empty string for any.
name - Filter for a specific input name attribute, null or an empty string for any.

Returns:
An array of HTMLInput DOM objects.

Given a form ID or reference to a form element, will return a list of HTMLElementInput obejcts. Note that it only returns elements that use the input tag, and will not return textarea or select fields. You can specify the input type and/or name as a filter. If both the type and name are specified, both need to match for a field to be returned.

var allInputs = Form.getInputs('theForm');
var checkboxes = Form.getInputs('theForm', 'checkbox');
var firstname = Form.getInputs('theForm', null, 'firstname');

Form.reset(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Resets the form to it's initial values. This is the same as when a user clicks on an HTML reset button.

Form.serialize(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
A URL encoded querystring.

Loops though all of the form controls and returns a querystring value based on the current control values. This is useful when you need to pass the form values to some page other then the target of the form, as you might do in an AJAX query.

// send the form values to somepage.jsp
var params = Form.serialize('theForm');
document.location = 'somepage.jsp?' + params;

---

This concludes the first installment of Prototype documentation. Please feel free to comment on this entry and suggest further information that should be added.

Tags

javascript Prototype reference