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.

1. 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" }
   } );

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