Field Plug-in

This plugin greatly expands the ability to retrieve and set values in forms beyond jQuery's standard val() method (and Mike Alsup's Form Plug-in's fieldArray() method) by allowing you to interact with all types of form field elements (except input[@type="file"], which is a read-only element.) It works the same way for text elements as it does for radio, checkbox and select elements.

The plug-in was built on the concept that you want to manipulate the fields like their traditional variables. Selectors should be written to query a specific field object (i.e. elements that would be linked together via a common name attribute, for example $("input[@name='myRadioButton']").)

Elements that return multiple values are either separated by a comma or returned as an array based on which methods you invoke.

For elements that allow more than one option to be select (select and checkbox elements) you can specify a comma delimited list or an array of values to mark multiple options as being selected.

Syntax Examples

• $("input[@name='users']").fieldArray();
  Returns an array of all values selected or entered for the selector. If the selector was a checkbox or select element, the array would contain the value of each item selected/checked.
• $("input[@name='users']").fieldArray(["dan", "joern", "karl", "john"]);
  Sets the value of the field to "dan,joern,karl,john". If the selector was a checkbox or select element, then the options with the values of "dan", "joern", "karl" and "john" would be selected--all other options would be unselected.
• $("input[@name='users']").getValue();
  Returns a comma delimited string of all values selected or entered for the selector. If the selector was a checkbox or select element, the string would contain the value of each item selected/checked as a separate item in the list.
• $("input[@name='users']").setValue("dan,joern,karl,john");
  Sets the value of the field to "dan,joern,karl,john". If the selector was a checkbox or select element, then the options with the values of "dan", "joern", "karl" and "john" would be selected--all other options would be unselected.
• $("#formName").formHash();
  Returns a hash map of all the form fields and their values.
• $("#formName").formHash({"name": "Dan G. Switzer, II", "state": "OH"});
  Returns the jQuery chain and sets the fields "name" and "state" with the values "Dan G. Switzer, II" and "OH" respectively.
• $("input:checkbox").limitSelection(3);
$("input:checkbox").limitSelection({limit: 3});
  Limits the user from being able to select more than 3 items in a checkbox/select element. Once the user selects more than 3 items, an error alert() message is displayed.
• $("input:checkbox").limitSelection(3, {onsuccess: successCallback, onfailure: errorCallback});
$("input:checkbox").limitSelection({limit: 3, onsuccess: successCallback, onfailure: errorCallback});
  Limits the user from being able to select more than 3 items in a checkbox/select element. If 3 items or less are selected, the successCallback is executed. If more than 3 items is selected, the errorCallback is executed.
• $("input:checkbox").createCheckboxRange();
  The createCheckboxRange() allows you to create a Gmail-like checkbox range selector. By clicking on a checkbox element and then [SHIFT] clicking on an additional checkbox element, the entire range of checkbox elements between the first and second elements clicked with be checked or unchecked (based upon the status of the first checkbox clicked.)
• $("input:checkbox").createCheckboxRange(callback);
  Triggers the callback function to run each time the checked status of a field changes. This allows you to attach behaviors--such as highlighting the checkbox's row. This callback function's "this" reference is to the jQuery object who's status was changed. An single argument is passed that's a boolean indicating whether or not the field is checked or not.
• $("#formName").autoAdvance();*
  The autoAdvance() will search through the matching elements in the selector for any text-based input fields. It will then apply an onkeyup event that will take the user to the next field in the tabIndex (within the context of the form) when the maxlength value of the field has been reached.
• $("#formName").autoAdvance(callback);*
  Automatic advances to next field and triggers the callback function on the field the user left. This callback function's "this" reference is to the jQuery object who's field your leaving. An single argument is passed that's a reference to the field that's being moved to.
• $("input[@name='users']").moveNext();*
  This would move the focus to the next field in the tabIndex array from the "users" field. If the next tabItem is outside of the form's context, the first element in the form will be selected.
• $("input[@name='users']").movePrev();*
  This would move the focus to the previous field in the tabIndex array from the "users" field. If the previous tabItem is outside of the form's context, the last element in the form will be selected.
• $("input[@name='users']").moveIndex(3);*
  This would move the focus to the third element in the tabIndex array. If the value "3" is outside the tabIndex array for the current form, then the last field would be selected.
• $("input[@name='users']").getTabIndex();*
  This returns the tabIndex for the current field as it relates to the parent
  form object.

* The tabIndex navigation methods attempt to follow the spec for tabbing through elements. This means that elements that have a specified tabIndex take priority over elements that do not specify an index. Disabled items are skipped altogether. The major exception is that the methods will only move within the parent form object.