# Bootstrap Dual Listbox

Github project page

Bootstrap Dual Listbox is a responsive dual listbox widget optimized for Twitter Bootstrap. It works on all modern browsers and on touch devices.

## Example with default values

The dual listbox is created from a select multiple by calling `.bootstrapDualListbox(settings);` on a selector. The selector can be any element, not just selects. When the method is called on a selector other than a select, then all select childrens are converted into dual list boxes.

    var demo1 = $('select[name="duallistbox_demo1[]"]').bootstrapDualListbox();

## Example with custom settings

    var demo2 = $('.demo2').bootstrapDualListbox({
      nonSelectedListLabel: 'Non-selected',
      selectedListLabel: 'Selected',
      preserveSelectionOnMove: 'moved',
      moveOnSelect: false,
      nonSelectedFilter: 'ion ([7-9]|[1][0-2])'
    });

## Dynamically add options to the selects

The options must be added to/removed from the original select.
Note that the `refresh` must be run on it after manipulating the options.

If there are some highlighted options in the lists, then calling the `refresh` method with the optional `true` parameter results the highlights to be removed. Example usage: `demo2.bootstrapDualListbox('refresh', true);`
It has meaning only when `moveOnSelect` setting is `false`.

    $("#demo2-add").click(function() {
      demo2.append('ApplesOranges');
      demo2.bootstrapDualListbox('refresh');
    });

    $("#demo2-add-clear").click(function() {
      demo2.append('ApplesOranges');
      demo2.bootstrapDualListbox('refresh', true);
    });

## Settings

When calling $("#element").bootstrapDualListbox() you can pass a parameters object with zero or more of the following:

Option | Description
--- | ---
`bootstrap2Compatible` | `false`: set this to `true` if you want graphic compatibility with Bootstrap 2.
`filterTextClear` | `'show all'`: the text for the "Show All" button.
`filterPlaceHolder` | `'Filter'`: the placeholder for the `input` element for filtering elements.
`moveSelectedLabel` | `'Move selected'`: the label for the "Move Selected" button.
`moveAllLabel` | `'Move all'`: the label for the "Move All" button.
`removeSelectedLabel` | `'Remove selected'`: the label for the "Remove Selected" button.
`removeAllLabel` | `'Remove all'`: the label for the "Remove All" button.
`moveOnSelect` | `true`: determines whether to move `options` upon selection. This option is forced to `true` on the Android browser.
`preserveSelectionOnMove` | `false`: can be `'all'` (for selecting both moved elements and the already selected ones in the target list) or `'moved'` (for selecting moved elements only)
`selectedListLabel` | `false`: can be a string specifying the name of the selected list.
`nonSelectedListLabel` | `false`: can be a string specifying the name of the non selected list.
`helperSelectNamePostfix` | `'_helper'`: The added selects will have the same name as the original one, concatenated with this string and 1 (for the non selected list, e.g. element_helper1) or 2 (for the selected list, e.g. element_helper2).
`selectorMinimalHeight` | `100`: represents the minimal height of the generated dual listbox.
`showFilterInputs` | `true`: whether to show filter inputs.
`nonSelectedFilter` | `''`: initializes the dual listbox with a filter for the non selected elements. This is applied only if `showFilterInputs` is set to `true`.
`selectedFilter` | `''`: initializes the dual listbox with a filter for the selected elements. This is applied only if `showFilterInputs` is set to `true`.
`infoText` | `'Showing all {0}'`: determines which string format to use when all options are visible. Set this to `false` to hide this information. Remember to insert the `{0}` placeholder.
`infoTextFiltered` | `'<span class="label label-warning">Filtered</span> {0} from {1}'`: determines which element format to use when some element is filtered. Remember to insert the `{0}` and `{1}` placeholders.
`infoTextEmpty` | `'Empty list'`: determines the string to use when there are no options in the list.
`filterOnValues` | `false`: set this to `true` to filter the options according to their values and not their HTML contents.
`eventMoveOverride` | `false`: set this to `true` to allow your own implementation of the move event.
`eventMoveAllOverride` | `false`: set this to `true` to allow your own implementation of the moveall event.
`eventRemoveOverride` | `false`: set this to `true` to allow your own implementation of the remove event.
`eventRemoveAllOverride` | `false`: set this to `true` to allow your own implementation of the removeall event.

## Methods

You can modify the behavior and aspect of the dual listbox by calling its methods, all of which accept a `value` and a `refresh` option. The `value` determines the new parameter value, while `refresh` (optional, defaults to `false`) tells whether to update the plugin UI or not.

To call methods on the dual listbox instance, use the following syntax:

    $(selector).bootstrapDualListbox(methodName, parameter);

Note: when making multiple chained calls to the plugin, set `refresh` to true to the last call only, in order to make a unique UI change; alternatively, you can also call the `refresh` method as your last one.

Here are the available methods:

Method | Description
--- | ---
`refresh()` | update the plugin element UI.
`destroy()` | restore the original `select` element and delete the plugin element.
`getContainer()` | get the container element.
`setBootstrap2Compatible(value, refresh)` | change the `bootstrap2Compatible` parameter.
`setFilterTextClear(value, refresh)` | change the `filterTextClear` parameter.
`setFilterPlaceHolder(value, refresh)` | change the `filterPlaceHolder` parameter.
`setMoveSelectedLabel(value, refresh)` | change the `moveSelectedLabel` parameter.
`setMoveAllLabel(value, refresh)` | change the `moveAllLabel` parameter.
`setRemoveSelectedLabel(value, refresh)` | change the `removeSelectedLabel` parameter.
`setRemoveAllLabel(value, refresh)` | change the `removeAllLabel` parameter.
`setMoveOnSelect(value, refresh)` | change the `moveOnSelect` parameter.
`setPreserveSelectionOnMove(value, refresh)` | change the `preserveSelectionOnMove` parameter.
`setSelectedListLabel(value, refresh)` | change the `selectedListLabel` parameter.
`setNonSelectedListLabel(value, refresh)` | change the `nonSelectedListLabel` parameter.
`setHelperSelectNamePostfix(value, refresh)` | change the `helperSelectNamePostfix` parameter.
`setSelectOrMinimalHeight(value, refresh)` | change the `selectOrMinimalHeight` parameter.
`setShowFilterInputs(value, refresh)` | change the `showFilterInputs` parameter.
`setNonSelectedFilter(value, refresh)` | change the `nonSelectedFilter` parameter.
`setSelectedFilter(value, refresh)` | change the `selectedFilter` parameter.
`setInfoText(value, refresh)` | change the `infoText` parameter.
`setInfoTextFiltered(value, refresh)` | change the `infoTextFiltered` parameter.
`setInfoTextEmpty(value, refresh)` | change the `infoTextEmpty` parameter.
`setFilterOnValues(value, refresh)` | change the `filterOnValues` parameter.
`setEventMoveOverride(value, refresh)` | change the `eventMoveOverride` parameter.
`setEventMoveAllOverride(value, refresh)` | change the `eventMoveAllOverride` parameter.
`setEventRemoveOverride(value, refresh)` | change the `eventRemoveOverride` parameter.
`setEventRemoveAllOverride(value, refresh)` | change the `eventRemoveAllOverride` parameter.