Prototype JavaScript framework - Form

request

2007-03-09T18:38:00Z

request([options]) -> new Ajax.Request

A convenience method for serializing and submitting the form via an Ajax.Request to the URL of the form’s action attribute. The options parameter is passed to the Ajax.Request instance, allowing to override the HTTP method and to specify additional parameters.

Options passed to request() are intelligently merged with the underlying Ajax.Request options:

If the form has a method attribute, its value is used for the Ajax.Request method option. If a method option is passed to request(), it takes precedence over the form’s method attribute. If neither is specified, method defaults to “POST”.
Key-value pairs specified in the parameters option (either as a hash or a query string) will be merged with (and take precedence over) the serialized form parameters.

Example

Suppose you have this HTML form:

<form id="person-example" method="POST" action="/user/info">
  <fieldset><legend>User info</legend>
  <div><label for="username">Username:</label>
    <input type="text" name="username" id="username" value="" /></div>
  <div><label for="age">Age:</label>
    <input type="text" name="age" id="age" value="" size="3" /></div>

  <div><label for="hobbies">Your hobbies are:</label>
  <select name="hobbies[]" id="hobbies" multiple="multiple">
    <option>coding</option>
    <option>swimming</option>
    <option>hiking</option>
    <option>drawing</option>
  </select>
 </div>
  <div class="buttonrow"><input type="submit" value="serialize!" /></div>
  </fieldset>
</form>

You can easily post it with Ajax like this:


$('person-example').request(); //done - it's posted

// do the same with a callback:
$('person-example').request({
  onComplete: function(){ alert('Form data saved!') }
})

To override the HTTP method and add some parameters, simply use method and parameters in the options. In this example we set the method to GET and set two fixed parameters: interests and hobbies. The latter already exists in the form but this value will take precedence.

$('person-example').request({
  method: 'get',
  parameters: { interests:'JavaScript', 'hobbies[]':['programming', 'music'] },
  onComplete: function(){ alert('Form data saved!') }
})

Form

2006-12-05T21:44:00Z

Form is a namespace and a module for all things form-related, packed with form manipulation and serialization goodness. While it holds methods dealing with forms as whole, its submodule Form.Element deals with specific form controls.

Most of these methods are also available directly on FORM elements that have been extended (see “How Prototype extends the DOM”).

findFirstElement

2006-11-02T23:21:00Z

findFirstElement(formElement) -> HTMLElement

Finds first non-hidden, non-disabled form control.

The returned object is either an INPUT, SELECT or TEXTAREA element. This method is used by the focusFirstElement() method.

Note

The result of this method is the element that comes first in the document order, not the tabindex order.

focusFirstElement

2006-11-02T23:21:00Z

focusFirstElement(formElement) -> HTMLFormElement

Gives keyboard focus to the first element of the form.

Uses Form.findFirstElement() to get the first element and calls activate() on it. This is useful for enhancing usability on your site by bringing focus on page load to forms such as search forms or contact forms where a user is ready to start typing right away.

enable

2006-11-02T23:20:00Z

enable(formElement) -> HTMLFormElement

Enables a fully or partially disabled form.

Enabling the form is done by iterating over form elements and enabling them.

Example

See the interactive example in the disable() method, which is basically it.

Note

This will enable all form controls regardless of how they were disabled (by scripting or by HTML attributes).

getInputs

2006-11-02T23:19:00Z

getInputs(formElement [, type [, name]]) -> array

Returns a collection of all INPUT elements in a form. Use optional type and name arguments to restrict the search on these attributes.

Example

var form = $('myform')

form.getInputs()       // -> all INPUT elements
form.getInputs('text') // -> only text inputs

var buttons = form.getInputs('radio', 'education')
// -> only radio buttons of name "education"

// now disable these radio buttons:
buttons.invoke('disable')

Note

Input elements are returned in the document order, not the tabindex order.

disable

2006-11-02T23:19:00Z

disable(formElement) -> HTMLFormElement

Disables the form as whole. Form controls will be visible but uneditable.

Disabling the form is done by iterating over form elements and disabling them.

Can I try it?

Sure, here's an example:

User info

<label for="username">Username:</label> <input name="username" type="text" id="username" value="Sulien" />

<label for="hobbies">Your hobbies are:</label> <select name="hobbies" id="hobbies" multiple="multiple"> <option>coding</option> <option>swimming</option> <option>hiking</option> <option>drawing</option> </select>

<button onclick="var form = $('disable-example'); form[form.disabled ? 'enable' : 'disable'](); form.disabled = !form.disabled;">Toggle disabled!</button>

</form>

Code attached to the onclick handler for the button is:

var form = $('disable-example');
// cycle between calling form.disable() and form.enable()
form[form.disabled ? 'enable' : 'disable']();
form.disabled = !form.disabled;

Note

Keep in mind that disabled elements are skipped by serialize methods! You cannot serialize a disabled form.

serializeElements

2006-11-02T23:18:00Z

serializeElements(elements[, getHash = false]) -> string

Serialize an array of form elements to a string suitable for Ajax requests (default behavior) or, if optional getHash evaluates to true, an object hash where keys are form control names and values are data..

The preferred method to serialize a form is Form.serialize. Refer to it for further information and examples on the getHash parameter. However, with serializeElements you can serialize specific input elements of your choice, allowing you to specify a subset of form elements that you want to serialize data from.

Example

To serialize all input elements of type "text":


Form.serializeElements( $('myform').getInputs('text') )
// -> serialized data

getElements

2006-11-02T23:18:00Z

getElements(formElement) -> array

Returns a collection of all form controls within a form.

Note

OPTION elements are not included in the result; only their parent SELECT control is.

serialize

2006-11-02T23:15:00Z

serialize(formElement[, getHash = false]) -> String | object

Serialize form data to a string suitable for Ajax requests (default behavior) or, if optional getHash evaluates to true, an object hash where keys are form control names and values are data.

Depending of whether or not the optional parameter getHash evaluates to true, the result is either an object of the form {name: "johnny", color: "blue"} or a string of the form "name=johnny&color=blue", suitable for parameters in an Ajax request. This method mimics the way browsers serialize forms natively so that form data can be sent without refreshing the page.

As of Prototype 1.5 the preferred form of passing parameters to an Ajax request is with an object hash. This means you should pass true for the optional argument. The old behavior (serializing to string) is kept for backwards-compatibility.

Interactive example

The following code is all there is to it:


$('person-example').serialize()
// -> 'username=sulien&age=22&hobbies=coding&hobbies=hiking'

$('person-example').serialize(true)
// -> {username: 'sulien', age: '22', hobbies: ['coding', 'hiking']}

Try it for yourself!

User info

<label for="username">Username:</label> <input name="username" type="text" id="username" value="" />

</form>

Notes

Disabled form elements are not serialized (as per W3C HTML recommendation). Also, file inputs are skipped as they cannot be serialized and sent using only JavaScript.

Keep in mind that "hobbies" multiple select should really be named "hobbies[]" if we're posting to a PHP or Ruby on Rails backend because we want to send an array of values instead of a single one. This has nothing to do with JavaScript - Prototype doesn't do any magic with the names of your controls, leaving these decisions entirely up to you.

reset

2006-11-02T23:12:00Z

reset(formElement) -> HTMLFormElement

Resets a form to its default values.

Example usage:

Form.reset('contact')

// equivalent:
$('contact').reset()

// both have the same effect as pressing the reset button

This method allows you to programatically reset a form. It is a wrapper for the reset() method native to HTMLFormElement.