jQuery Field Plug-in

# jQuery Field Plug-in (v0.7)

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.

## Download

Download the plug-in:
jquery.field.js
jquery.field.min.js

## Interactive Examples

Choice a selector below and click the getValue() or setValue() buttons to test the functionality on those field elements.

jQuery selector:

Field Plug-in Test

`input[type="text"]`

`input[type="password"]`

`input[type="hidden"]`

`input[type="radio"]` Option 1 Option 2 Option 3 Option 4 Option 5

`input[type="checkbox"]` Option 1 Option 2 Option 3 Option 4 Option 5

`select[type="select-one"]`

`select[type="select-multiple"]`

`textarea` Here is some text!

`input[type="button"]`

`input[type="submit"]`

`input[type="reset"]`

$.limitSelection() Examples
You can not select more than 3 of the following items:
Option 1 Option 2 Option 3 Option 4 Option 5
You can only select 2 options from the following:

NOTE: If a user has selected more than desired number of selections the first X number of items in the option array will be selected. While not ideal, there's no good way to track users who selected multiple options via a click-drag or [SHIFT]+click.

$.createCheckboxRange() Examples

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.) A callback function is used to highlight the <label> when the status of the elements "checked" status changes.

Option 1
Option 2
Option 3
Option 4
Option 5

You can change the default key binding by changing the `checkboxRangeKeyBinding` default setting using either the `$.Field.setDefaults()` method or with the command:
`$.Field.setProperty("checkboxRangeKeyBinding", "ctrlKey");` (click to change behavior.)

Field Navigation Methods

The Field plug-in contains several methods that will help you automatically navigate to the next form element. jQuery honors the tabIndex of your form elements (within the form object itself.)

This example shows how the tabIndex is honored within the parent form object. Type in a single character to auto-advance to the next field in the tabIndex (or use the [TAB] key to view the native behavior.)

tabIndex 1: tabIndex 3: tabIndex 2: tabIndex 4: tabIndex 6: tabIndex 5: tabIndex 7:

The below examples show off how you can you can easily configure a field set to move from one element to the next when the maxlength of characters has been reached.

Phone: () -

## 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.