These methods allow scripts to read and transform the values of fields in web forms.
|
Collects the values in a form into an array of objects. .formToArray([semantic]) |
semantic(optional): Whether to force strict HTML ordering of fields. The default value isfalse.
The .formToArray method fetches the values of a form, and organizes them into a data structure that is appropriate for passing to the jQuery AJAX functions such as $.ajax(), $.post(), and .load(). It can handle forms with any standard field type.
Given the form, illustrated in the .ajaxFor() discussion, the .formToArray method will return a JavaScript array of the form values:
[
{name: city, value: Morton},
{name: state, value: IL},
{name: comment, value: Eric the Red is my hero!},
{name: villages, value: 50},
{name: tactic, value: pillage},
{name: gear[helmet], value: yes},
{name: gear[longboat], value: yes}
]Each object in the array has a name and a value property. Checkbox elements that are not checked do not get represented in the array.
If the semantic argument is set to true, then the fields listed in the array will be guaranteed to be ordered as they are in the HTML source. If the form contains no <input> elements of type image, then this will already be the case. Avoid using this option unless it is needed, as the extra processing involved will slow down the method.
|
Collects the values in a form into a serialized string. .formSerialize([semantic]) |
semantic(optional): Whether to force strict HTML ordering of fields. The default value isfalse.
The .formSerialize method fetches the values of a form, and converts them into a string that is appropriate for passing as a query string for a GET request. It can handle forms with any standard field type.
Given the form illustrated in the .ajaxFor() discussion, the .formSerialize method will return a string representation of the form values:
city=Morton&state=IL&comment=Eric%20the%20Red%20is%20my%20hero! &villages=50&tactic=pillage&gear%5Bhelmet%5D=yes &gear%5Blongboat%5D=yes
Each of the fields shows up as a key-value pair in the string. Checkbox elements that are not checked do not get represented in the string. The string is URL-encoded as necessary.
If the semantic argument is set to true, then the fields listed in the string will be guaranteed to be ordered as they are in the HTML source. If the form contains no <input> elements of type image, then this will already be the case. Avoid using this option unless it is needed, as the extra processing involved will slow down the method.
|
Collects the values of a set of fields into a serialized string. .fieldSerialize([successful]) |
successful(optional): Whether to prune the included field values to successful ones. The default value istrue.
Like the .formSerialize method before it, the .fieldSerialize method fetches the values of a form, and converts them into a string that is appropriate for passing as a query string for a GET request. However, .fieldSerialize() acts on a jQuery object that references individual fields rather than the form as a whole.
It can handle fields of any standard type, such as <select> menus:
<select name="villages" id="villages"> <option value="0">none</option> <option value="5" selected="selected">1-5</option> <option value="10">6-10</option> <option value="20">11-20</option> <option value="50">21-50</option> <option value="100">51-100</option> <option value="more">over 100</option> </select>
The user can then select any option:
The value is pulled from the currently selected option, and the .fieldSerialize method will return a string representation of this value:
villages=50
Each of the given fields shows up as a key-value pair in the string. Checkbox elements that are not checked do not get represented in the string. The string is URL-encoded as necessary.
By default, fields are not represented in the string if they are not successful, as defined in the W3C specification for HTML forms:
http://www.w3.org/TR/html4/interact/forms.html#h-17.13.2
Successful fields are the ones that are submitted to the server during a normal form submission operation. For example, checkboxes that are currently checked are successful; unchecked ones are not. It is rare to want the values of unsuccessful fields, but if this is required, the successful parameter of .fieldSerialize() can be set to false.
Given the form illustrated in the .ajaxFor() discussion, .fieldSerializer() includes only checked radio buttons and checkboxes when successful is set to true:
tactic=loot&gear%5Bhelmet%5D=yes&gear%5Bgoat%5D=yes
But when successful is set to false, fieldSerializer() includes the unselected options as well:
tactic=loot&tactic=pillage&tactic=burn&gear%5Bhelmet%5D=yes &gear%5Blongboat%5D=yes&gear%5Bgoat%5D=yes
|
Collects the values of a set of fields into an array of strings. .fieldValue([successful]) $.fieldValue(element[, successful]) |
successful(optional): Whether to prune the included field values to successful ones. The default value istrue.
element: The form input element whose value is to be retrieved.successful(optional): Whether to prune the included field values to successful ones. The default value istrue.
The .fieldValue() method and the $.fieldValue() function both fetch the values of a form, returning them as an array of strings. The .fieldValue() method acts on a jQuery object that references individual fields, while the $.fieldValue() function performs the same task on the field element passed as its first parameter.
These operations can handle fields of any standard type, such as <select> menus:
<select name="villages" id="villages"> <option value="0">none</option> <option value="5" selected="selected">1-5</option> <option value="10">6-10</option> <option value="20">11-20</option> <option value="50">21-50</option> <option value="100">51-100</option> <option value="more">over 100</option> </select>
The user can then select any option:
The value is pulled from the currently selected option, and the .fieldValue() method will return an array representation of this value:
[50]
Each of the given fields shows up as a string in the array. Checkbox elements that are not checked do not get represented in the array.
By default, fields are not represented in the array if they are not successful, as defined in the W3C specification for HTML forms:
http://www.w3.org/TR/html4/interact/forms.html#h-17.13.2
Successful fields are the ones that are submitted to the server during a normal form submission operation. For example, checkboxes that are currently checked are successful; unchecked ones are not. It is rare to want the values of unsuccessful fields, but if this is required, the successful parameter of .fieldValue() can be set to false.
Given the form illustrated in the .ajaxFor() discussion, .fieldValue() includes only checked radio buttons and checkboxes when successful is set to to true:
[loot, yes, yes]
But when successful is set to false, .fieldValue() includes the unselected options as well:
[loot, pillage, burn, yes, yes, yes]
The .fieldValue method always returns an array; if there are no values to report in the set of elements being acted upon, the result array will be empty. In contrast, the $.fieldValue function will return null if the field element in question is not successful.