PickAndChoose v1.2

See LICENSE for this software's licensing terms.

PickAndChoose is a jQuery plugin which allows you make selections from a list of displayed items. There are two boxes: one box contains a list of available items and the other displays the items you've selected. You select and deselect items by using buttons which sit between the two boxes. When you select an item, it moves from the 'available' box to the 'selected' box. When you deselect an item, the opposite happens. You can also select or deselect all items at once, for either box.

Features

Supports unlimited simultaneous instances
Definable CSS classes make the widget highly styleable
Supports a callback on change

Initialization

There are two ways to initialize PickAndChoose; they differ based on the source of the data for your <select> boxes. The approach you choose affects which configuration options are used and required at initialization time. These details are in the Configuration Options section below.

You can pass the data to the plugin as key/value pairs. With this approach, PickAndChoose constructs all of the HTML for you.

<div id="myPicker"></div>

$( "#myPicker" ).pickAndChoose( {
   unselectedItems : { "Choice 1" : "choice1",
                       "Choice 3" : "choice3" },

   selectedItems   : { "Choice 2" : "choice2" }
} );

Alternatively, PickAndChoose can use pre-existing, pre-populated <select>s.

<div id="myPicker">
   <select id="availableItemsId" name="availableItems">
      <option value="choice1">Choice 1</option>
      <option value="choice2">Choice 2</option>
   </select>

   <select id="chosenItemsId" name="chosenItems">
   </select>
</div>

$( "#myPicker" ).pickAndChoose( {
   createSelectElements : false,
   unselectedId         : "availableItemsId",
   selectedId           : "chosenItemsId"
} );

Notes

If you have more than one PickAndChoose widget in your page, then you must specify unique values for unselectedId, unselectedName, selectedId and selectedName.
You cannot mix-and-match the way you initialize your <select>s. You must use either the first approach for both, or the second approach for both.

See the included HTML file for more in-depth examples.

Configuration Options

Property	Description	Default Value
`addCssClasses`	If `true`, PickAndChoose will apply CSS classes. If false, no CSS classes will be applied, even if you override their default values.	true
`containerClass`	The CSS class of the <div> which contains everything	pacContainer
`unselectedContainerClass`	The CSS class of the <div> containing the <select> of unselected items	pacUnselectedContainer
`selectedContainerClass`	The CSS class of the <div> containing the <select> of selected items	pacSelectedContainer
`buttonContainerClass`	The CSS class of the <div> containing the buttons	pacButtonContainer
`buttonSelectClass`	The CSS class of the select <button>	pacButtonSelect
`buttonSelectAllClass`	The CSS class of the select-all <button>	pacButtonSelectAll
`buttonDeselectClass`	The CSS class of the deselect <button>	pacButtonDeselect
`buttonDeselectAllClass`	The CSS class of the deselect-all <button>	pacButtonDeselectAll
`optionCssClass`	A CSS class to apply to all <options>s	null
`buttonSelectText`	The text of the select button	>
`buttonSelectAllText`	The text of the select-all button	>>
`buttonDeselectText`	The text of the deselect button	<
`buttonDeselectAllText`	The text of the deselect-all button	<<
`createSelectElements`	If `true`, <select> elements will be created based on the data you provide in the `unselectedItems` and `selectedItems` properties, and they will be named according to the `unselectedId`, `unselectedName`, `selectedId` and `selectedName` properties. If `false`, the `unselectedId` and `selectedId` properties will be used to locate preexisting <select>s in the page.	true
`unselectedId`	The ID of the <select> containing the unselected items, whether the <select> is created for you or you provide your own	pacUnselectedItems
`unselectedName`	The name of the <select> containing the unselected items. If you provide your own <select> elements instead of having them constructed for you, this setting is ignored.	pacUnselectedItems
`selectedId`	The ID of the <select> containing the selected items, whether the <select> is created for you or you provide your own	pacSelectedItems
`selectedName`	The name of the <select> containing the selected items. If you provide your own <select> elements instead of having them constructed for you, this setting is ignored.	pacSelectedItems
`unselectedItems`	Key/value pairs of items to populate the unselected items' <select> with. If you provide your own <select> elements instead of having them constructed for you, this setting is ignored.	null
`selectedItems`	Key/value pairs of items to populate the selected items' <select> with. If you provide your own <select> elements instead of having them constructed for you, this setting is ignored.	null
`unhighlightAfterMove`	Determines whether to unhighlight an item after moving it to the other <select>. Highlighted items appear as if they've been clicked.	true
`onChangeCallback`	A callback function to execute when the user uses the buttons. The callback only fires if the user's action resulted in a change.	null
`showErrors`	Determines whether to display initialization errors in the page. If set to `true`, your users will see them, so you might choose to treat this as a debug option. Regardless of the setting, the plugin will throw initialization errors as exceptions.	false

Using a Callback

If you implement a callback function, it must accept three parameters:

Parameter	Data Type	Description
`operation`	string	Tells you whether the user selected or deselected items. Possible values are `select` and `deselect`.
`recipient`	jQuery object	The <select> which received the items that were selected/deselected
`items`	object array	Contains the data that was written to the recipient <select>. Access the data using [object].key and [object].value.

kloverde/jquery-PickAndChoose

PickAndChoose v1.2

Features

Initialization

Configuration Options

Using a Callback