Prototype JavaScript framework

namespace Form

Description

Utilities for dealing with forms in the DOM.

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

Many of these methods are also available directly on form elements.

Related utilities

$F

Methods

Class methods

  • disable #

    Form.disable(form) ⇒ Element
    Form#disable() ⇒ Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • enable #

    Form.enable(form) ⇒ Element
    Form#enable() ⇒ Element

    Enables a fully- or partially-disabled form.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • findFirstElement #

    Form.findFirstElement(form) ⇒ Element
    Form#findFirstElement() ⇒ Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • focusFirstElement #

    Form.focusFirstElement(form) ⇒ Element
    Form#focusFirstElement() ⇒ Element

    Gives keyboard focus to the first element of the form. Returns the form.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getElements #

    Form.getElements(form) ⇒ [Element…]
    Form#getElements() ⇒ [Element…]

    Returns a collection of all controls within a form.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getInputs #

    Form.getInputs(form [, type [, name]]) ⇒ [Element…]
    Form#getInputs([type [, name]]) ⇒ [Element…]
    • type (String) – A value for the type attribute against which to filter.
    • name (String) – A value for the name attribute against which to filter.

    Returns a collection of all INPUT elements in a form.

    Use optional type and name arguments to restrict the search on these attributes.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • request #

    Form.request(form[, options]) ⇒ Ajax.Request
    Form#request([options]) ⇒ Ajax.Request
    • options (Object) – Options to pass along to the Ajax.Request constructor.

    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 one to override the HTTP method and/or specify additional parameters and callbacks.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • reset #

    Form.reset(form) ⇒ Element

    Resets a form to its default values.

  • serialize #

    Form.serialize(form[, options]) ⇒ String | Object
    Form#serialize([options]) ⇒ String | Object
    • options (Object) – A list of options that affect the return value of the method.

    Serialize form data to an object or string suitable for Ajax requests.

    See Form.serializeElements for details on the options.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • serializeElements #

    Form.serializeElements(elements[, options]) ⇒ String | Object
    • elements (Array) – A collection of elements to include in the serialization.
    • options (Object) – (Optional) A set of options that affect the return value of the method.

    Serialize an array of form elements to an object or string suitable for Ajax requests.

    As per the HTML spec, disabled fields are not included.

    If multiple elements have the same name and we're returning an object, the value for that key in the object will be an array of the field values in the order they appeared on the array of elements.

    The Options

    The options allow you to control two things: What kind of return value you get (an object or a string), and whether and which submit fields are included in that object or string.

    If you do not supply an options object at all, the options { hash: false } are used.

    If you supply an options object, it may have the following options:

    • hash (Boolean): true to return a plain object with keys and values (not a Hash; see below), false to return a String in query string format. If you supply an options object with no hash member, hash defaults to true. Note that this is not the same as leaving off the options object entirely (see above).
    • submit (Boolean | String): In essence: If you omit this option the first submit button in the form is included; if you supply false, no submit buttons are included; if you supply the name of a submit button, the first button with that name is included. Note that the false value must really be false, not falsey; falsey-but-not-false is like omitting the option.

    (Deprecated) If you pass in a Boolean instead of an object for options, it is used as the hash option and all other options are defaulted.

    A hash, not a Hash

    If you opt to receive an object, it is a plain JavaScript object with keys and values, not a Hash. All JavaScript objects are hashes in the lower-case sense of the word, which is why the option has that somewhat-confusing name.