UIZE JavaScript Framework

MODULES Uize.Dom.Form

1. Introduction

The Uize.Dom.Form package provides convenient methods for harvesting values from - and setting values for - many form elements in a single operation.

DEVELOPERS: Guang-Yu Xu, Chris van Rensburg, Ben Ilegbodu

1.1. Examples

There are no dedicated showcase example pages for the Uize.Dom.Form module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Dom.Form module...

SEARCH

1.2. Implementation Info

The Uize.Dom.Form module defines the Uize.Dom.Form package under the Uize.Dom namespace.

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Dom.Form.doForAll | Uize.Dom.Form.getValues | Uize.Dom.Form.setEnabled | Uize.Dom.Form.setValues

STATIC PROPERTIES

Uize.Dom.Form.moduleName | Uize.Dom.Form.pathToResources

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Dom.Form module.

2. Static Methods

2.1. Uize.Dom.Form.doForAll

Iterates through all the form elements found within a specified root node, calling the specified function for each node and passing the node reference as a parameter.

SYNTAX

Uize.Dom.Form.doForAll (rootNodeSTRorOBJ,actionFUNC);

The value of the rootNodeSTRorOBJ parameter can be a string, representing the id of the root node, or an object reference to the root node. The root node can be either a form tag, or any DOM node that contains all the desired form elements, such as a div or other type of element.

2.1.1. An Example

In the following example, there is a form tag containing a number of different form elements.

SAMPLE HTML

<form id="myForm">
  <input id="myForm-myText" name="myText" type="text" value="blah"/>
  <input id="myForm-myCheckbox" name="myCheckbox" type="checkbox" checked="checked"/>
  <select id="myForm-mySelect" name="mySelect">
    <option value="1">One</option>
    <option value="2" selected="selected">Two</option>
    <option value="3">Three</option>
  </select>
</form>

With the above HTML, you could call the method like this...

Uize.Dom.Form.doForAll (
  function (node) {
    node.className = 'formElement';
    Uize.Dom.Basics.wire (node,'change',handleNodeChange);
  }
);

This snippet of code would set the class attribute of each node to "formElment" as well as wire the handleNodeChange function to the onChange event of each node.

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Dom.Form.getValues

Harvests the values for all form elements found within a specified root node, and packages them into an object.

SYNTAX

valuesOBJ = Uize.Dom.Form.getValues (rootNodeSTRorOBJ);

The value of the rootNodeSTRorOBJ parameter can be a string, representing the id of the root node, or an object reference to the root node. The root node can be either a form tag, or any DOM node that contains all the desired form elements, such as a div or other type of element.

By default, the keys of the values object generated by this method will be named according to the name attribute of the form elements from which values are harvested. However, different variations of this method also allow the id attribute to be used, and allow an optional prefix to be specified that should be removed when generating the key names.

VARIATION 1

valuesOBJ = Uize.Dom.Form.getValues (rootNodeSTRorOBJ,useNodeIdBOOL);

When the optional useNodeIdBOOL parameter is specified, you can control whether or not the id attribute of form elements is used in naming the keys of the returned values object. Specifying the value true for this parameter will cause the id attribute to be used, while specifying the value false will cause the name attribute to be used.

VARIATION 2

valuesOBJ = Uize.Dom.Form.getValues (rootNodeSTRorOBJ,useNodeIdBOOL,prefixSTR);

When the optional prefixSTR parameter is specified, you can specify a prefix that should be stripped off the ids or names of form elements when generating key names for the returned values object.

2.2.1. An Example

In the following example, there is a form tag containing a number of different form elements.

SAMPLE HTML

<form id="myForm">
  <input id="myForm-myText" name="myText" type="text" value="blah"/>
  <input id="myForm-myCheckbox" name="myCheckbox" type="checkbox" checked="checked"/>
  <select id="myForm-mySelect" name="mySelect">
    <option value="1">One</option>
    <option value="2" selected="selected">Two</option>
    <option value="3">Three</option>
  </select>
</form>

With the above HTML, the statement Uize.Dom.Form.getValues ('myForm') would produce the following object (here we're using form element names as keys)...

// Uize.Dom.Form.getValues ('myForm') produces...
{
  myText:'blah',
  myCheckbox:true,
  mySelect:'2'
}

The statement Uize.Dom.Form.getValues ('myForm',true) would produce the following object (here we're using form element ids as keys)...

// Uize.Dom.Form.getValues ('myForm',true) produces...
{
  'myForm-myText':'blah',
  'myForm-myCheckbox':true,
  'myForm-mySelect':'2'
}

The statement Uize.Dom.Form.getValues ('myForm',true,'myForm-') would produce the following object (here we're using form element ids as keys, and we're stripping off the specified 'myForm-' prefix)...

// Uize.Dom.Form.getValues ('myForm',true,'myForm-') produces...
{
  myText:'blah',
  myCheckbox:true,
  mySelect:'2'
}

NOTES

see the corresponding Uize.Dom.Form.setValues static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Dom.Form.setEnabled

Enables or disables all of the form elements found within a specified root node, using the "disabled" node attribute.

SYNTAX

Uize.Dom.Form.setEnabled (rootNodeSTRorOBJ,mustEnableANYTYPE);

The value of the rootNodeSTRorOBJ parameter can be a string, representing the id of the root node, or an object reference to the root node. The root node can be either a form tag, or any DOM node that contains all the desired form elements, such as a div or other type of element.

While typically a Boolean, the mustEnableANYTYPE parameter can be of any type and the node(s) will be enabled if it resolves to true, and disabled if it resolves to false - with the exception of undefined, when the node(s) will be enabled (see explanation below).

VARIATION

Uize.Dom.Form.setEnabled (rootNodeSTRorOBJ);

When no mustEnableANYTYPE parameter is specified (or when its value is undefined), the node(s) will be enabled.

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Dom.Form.setValues

Lets you conveniently set the values for a set of form elements, using a values object.

SYNTAX

Uize.Dom.Form.setValues (valuesOBJ);

By default, the keys of the values object specified by the valuesOBJ parameter are used as the ids or names for identifying the form elements. So, for example, a values object with a key of username will set the value for the form element whose id or name is username.

VARIATION

Uize.Dom.Form.setValues (valuesOBJ,prefixSTR);

When the optional prefixSTR parameter is specified, then a prefix can be specific that will be added before the names of the keys in the values object, when generating the ids or names of their corresponding form elements. For example, when the value 'myForm-' is specified for the prefixSTR parameter, then a values object with a key of username will set the value for the form element whose id or name is myForm-username.

2.4.1. An Example

In the following example, there is a form tag containing a number of different form elements.

SAMPLE HTML

<form id="myForm">
  <input id="myForm-myText" name="myText" type="text"/>
  <input id="myForm-myCheckbox" name="myCheckbox" type="checkbox"/>
  <select id="myForm-mySelect" name="mySelect">
    <option value="1">One</option>
    <option value="2">Two</option>
    <option value="3">Three</option>
  </select>
</form>

SAMPLE JAVASCRIPT

Uize.Dom.Form.setValues (
  {
    myText:'blah',
    myCheckbox:true,
    mySelect:'2'
  },
  'myForm-'
);

After the above JavaScript statement has been executed, the text input with the id of myForm-myText will be set to the value 'blah', the checkbox with the id of myForm-myCheckbox will be checked, and the second option of the select element with the id of myForm-mySelect will be selected.

NOTES

see the corresponding Uize.Dom.Form.getValues static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Dom.Form.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Dom.Form.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module