Customizing the Tandem Select jQuery Plugin
The plugin relies on the Select menus and related components having specific class names that begin with 'tandem-select'.
The easiest way to get started is to cut and paste the HTML code from the template file (tandem_select_template.txt) and then customize it to fit your application.
The template uses a three column layout - Source (src) and Destination (dst) Select menus with the controls in between - all of which are wrapped in a container DIV.
The basic layout looks like this:
<div class='tandem-select-container'>
<div class='tandem-select-src-div'>
<select multiple='multiple' class='tandem-select-src-select'>
<option value="abc">Options go here</option>
</select>
</div>
<div class='tandem-select-controls-div'>
<input type="button" class="tandem-select-move-to-src" value="Add" />
<input type="button" class="tandem-select-move-to-dst" value="Remove" />
<input type="text" class="tandem-select-search-src"/>
</div>
<div class='tandem-select-dst-div'>
<select multiple='multiple' class='tandem-select-dst-select'
id='YOUR_SELECT_ID' name='YOUR_SELECT_NAME'></select>
</div>
</div>
<div style="clear: both;"></div>
DIVs
The container DIV with class 'tandem-select-container' is REQUIRED.
Within that are three DIVs that hold the Source Select menu, the Controls and the Destination Select menu respectively. These DIVs are OPTIONAL but they are useful for layout.
Select Menus
The Source Select menu MUST have the class 'tandem-select-src-select'. This is where you place your list of options
The Destination Select menu MUST have the class 'tandem-select-dst-select'. In addition you need to give this unique ID and NAME attributes.
The NAME attribute is the standard one that you would use for this key/value pair in the FORM that includes the Tandem Select.
The ID attribute is used by the plugin to identify this particular Tandem Select. You can have multiple Tandem Selects on a page, each with a unique ID. The value for the ID is arbitrary but some web application frameworks, such as Rails, have conventions for form element NAME and IDs that you will want to follow.
Buttons
There are two Buttons that are used to move options between the Source and Destination Select Menus. These MUST have the classes 'tandem-select-move-to-src' and 'tandem-select-move-to-dst' for the respective actions.
Search Field
Optionally you can include a Search field in the form of an INPUT text field with the class 'tandem-select-search-src'. Typing text into this will highlight options in the Source menu that match, making it easy to find specific options in a long list.
For the sake of completeness, you can create a search field for the Destination menu with the class 'tandem-select-search-dst', although this is probably not useful in most cases.
CSS
The look and layout of these elements is defined in the CSS file. The one that ships with this plugin should serve as a reasonable starting point.
One important style is defined in the class 'tandem-select-option-disabled'. By default, when options are moved to the Destination menu they remain in the Source menu, but appear in gray. If you prefer to hide the transferred options then set this class to 'display: none'.