The Forms Plugin provides extensions to the basic functionality provided by jQuery, as well as functions for automating the submission of Ajax forms.

Extensions to Basic Form Functionality

.val() becomes .fieldValue()

While the basic val() method simply provides the results of a test on the value attribute of the function itself, fieldValue() does a much more thorough job of getting the value information for a particular field:

• It gets an array of values if there are multiple checkboxes with the same name
• It gets an array of values for multiple-selects
• It allows you to specify the inclusion of only "successful" elements, as defined by the HTML spec. Successful elements include only elements that:
  • have a "name" attribute
  • have a current "value" attribute
  • are within a "form" element
  • are not disabled
  • are the submit button actually pressed. If there are more than one submit button, the ones that are not pressed are not successful
  • are "on" radio buttons
  • are "on" checkboxes
  • are selected options
  • are a file select with one or more files selected

A normal submit would include only "successful" controls. Trigger this behavior by passing true as the only parameter to fieldValue()

Note fieldValue, like val, returns the value of the first element in the jQuery object.

formToArray()

Gathers form data into an array of objects that can be passed to jQuery Ajax methods.

jQuery Ajax methods take an array of DOM elements, then gets the "name" and "value" from each element and submits the results. formToArray creates an array of objects that each contain "name" and "value" -- to emulate the array of DOM elements jQuery is expecting.

It optimizes the array by passing multiple objects for multiple selects and checkboxes, so that the serialized version finally passed on to the server will work as expected (as though it was an actually submitted form).

formToArray accepts a "semantic" option, which forces the array to be built in the order that the elements are on the page. This could be useful, for instance, if you're using a server-side framework to build a server-side array from a series of form objects with the name "list[]" (for example, Ruby on Rails and PHP). You activate this option by passing true as the only parameter to formToArray().

formSerialize()

This function serializes all of the elements in a form and returns a query string.

It uses the jQuery.param method, which takes a jQuery object or the results of formToArray (which emulates a jQuery object for the purpose of serialization).

fieldSerialize()

Same as formSerialize, but it serializes all of the elements in the jQuery object and returns a query string. For example, you can do $("select").fieldSerialize().

clearForm() and resetForm()

resetForm will reset each form in the jQuery object, which will return the values of each element to their original values (set in HTML).

clearForm will reset the values of each form element to blank:

• text, password, and textarea fields will be set to ""
• checkboxes and radio buttons will have checked = false applied
• select boxes will have selectedIndex = -1 applied

Ajax Help

ajaxForm()

ajaxForm provides a way to:

• automatically invoke ajaxSubmit on the submission of a particular form
• include the coordinates of the click on an <input type="image">
• include the name/value of the element used to submit the form

It takes the same single parameter as ajaxForm(), and simply delegates the entire operation to ajaxForm, with the exception of the submit button logic.

Note: Firefox will not be able to perfectly provide the x/y coordinates of the submit button click without the inclusion of dimensions.js. It is therefore recommended that you use dimensions.js if you want a guarantee of valid data.