API Documentation

##Disclaimer

All options are currently implemented at initialization stage only, meaning that setting an option after the widget has been initialized does not guarantee that the new value will be applied! This notice will be removed when all options will be fully implemented under satisfactory circonstances!

Options

• availableListPosition (string) (default: "right") : set where the available list should be positioned in the widget. For left and right, the list layout will be horizontal. For top and bottom, the list layout will be vertical.

    // initialize option
    $(selector).multiselect({ availableListPosition: 'left' });
  
    // get option value
    var collapsibleGroups = $(selector).multiselect('option', 'availableListPosition');
    // set option after initialization (require refresh)
    $(selector).multiselect('option', 'availableListPosition', 'left').multiselect('refresh');
  

• collapsableGroups (boolean) (default: true) : tells whether the option groups can be collapsed or not

    // initialize option
    $(selector).multiselect({ collapsableGroups: false });
  
    // get option value
    var collapsibleGroups = $(selector).multiselect('option', 'collapsableGroups');
    // set option after initialization (require refresh)
    $(selector).multiselect('option', 'collapsableGroups', false).multiselect('refresh');
  

• defaultGroupName (string) (default: "") : The name of the default group to display. Any option not inside an OPTGROUP element will be assigned to the default group. If showDefaultGroupHeader is set to true, then this setting will define the name of this group.

    // initialize option
    $(selector).multiselect({ defaultGroupName: 'Default' });
  
    // get option value
    var collapsibleGroups = $(selector).multiselect('option', 'defaultGroupName');
    // set option after initialization (require refresh)
    $(selector).multiselect('option', 'defaultGroupName', 'Default').multiselect('refresh');
  

• filterSelected (boolean) (default: false) : when using the search feature, will the selected elements also be filtered with the search query (true), or not (false) ?

    // initialize option
    $(selector).multiselect({ filterSelected: true });
  
    // get option value
    var collapsibleGroups = $(selector).multiselect('option', 'filterSelected');
    // set option after initialization
    $(selector).multiselect('option', 'filterSelected', true);
  

• locale (string) (default: "auto") : any valid locale, auto, or en empty string for default built-in strings if no locale is included. The auto value will try to locate the user's or browser's locale. If the locale is not found, the default build-in strings will be used.

    // initialize option
    $(selector).multiselect({ locale: 'fr' });
  
    // get option value
    var locale = $(selector).multiselect('option', 'locale');
    // set option after initialization (no refresh required)
    $(selector).multiselect('option', 'locale', 'fr');
  

• moveEffect (string) (default: null) : animate item selection using the specified jQuery UI Effect. Possible values include blind, bounce, clip, drop, explode, fold, highlight, puff, pulsate, shake, and slide.

    // initialize option
    $(selector).multiselect({ moveEffect: 'pulsate' });
  
    // get option value
    var moveEffect = $(selector).multiselect('option', 'moveEffect');
    // set option after initialization (no refresh required)
    $(selector).multiselect('option', 'moveEffect', 'pulsate');
  

• moveEffectOptions (object) (default: {}) : the effect options value

• moveEffectSpeed (string|int) (default: null) : string (slow, fast) or number in millisecond (ignored if moveEffect is show)

• optionRenderer (function) (default: false) : a function that will return the item element to be rendered in the list. The function will receive the <OPTION> element jQuery object and the option group name (if any) and should return a jQuery object of a DOM element.

• searchField (boolean|string) (default: "toggle") : Define the behaviour of the search functionality. Set to true to force the field always visible, set to false to disable the search feature (any call to the search method will be ignored), or set 'toggle' to toggle the search field on and off (any call to the search method should render the search field visible).

• searchHeader (string) (default: "available") : specify the list header that will receive the search field. For example, if you set the availableListPosition to "bottom", the search field will toggle in the middle of the widget. Unless you specify searchHeader to "selected", in which case the search field will be located at the top. You may also set filterSelected to true for even better results.

• selectionMode (string) (default: "click,d&d") : How options can be selected separated by commas. Supported moded are: "click", "dblclick" and "d&d". Note, drag and drop support may be disabled by not providing "d&d" to this option.

• showDefaultGroupHeader (boolean) (default: false) : if set to true, will show the default group for options that are not inside a OPTGROUP element.

• showEmptyGroups (boolean) (default: false) : if set to true, empty groups will be displayed. Otherwise, all empty groups will be hidden.

• splitRatio (float) (default: 0.55) : % of the left list's width of the widget total width

    // initialize option
    $(selector).multiselect({ splitRatio: 0.5 });
  
    // get option value
    var splitRatio = $(selector).multiselect('option', 'splitRatio');
    // set option after initialization (require refresh)
    $(selector).multiselect('option', 'splitRatio', 0.5).multiselect('refresh');
  

• sortable (boolean) (default: false) : Set if the user can reorder the selected options and groups.

    // initialize option
    $(selector).multiselect({ sortable: true });
  
    // get option value
    var collapsibleGroups = $(selector).multiselect('option', 'sortable');
    // set option after initialization (require refresh)
    $(selector).multiselect('option', 'sortable', true).multiselect('refresh');
  

• sortMethod (string|function) (default: "standard") : Tells how option items should be sorted. Set null for unsorted (will be displayed as in the original element); standard or natural for the build-in sort functions (sort items as strings); a sort function for custom sort, where the function will receive three arguments and the third being a boolean value indicating if the first two are group (true) or item (false) names, and the returned value should be a numeric value indicating if the first argument is greater (> 0), equal (= 0) or less (< 0) than the second argument.

    // sort option groups asc and items desc
    var _customSort = function(a, b, g) {
        if (a > b) return g ? 1 : -1;
        if (a < b) return g ? -1 : 1;
        return 0;
    };
  
    // initialize option
    $(selector).multiselect({ sortMethod: _customSort });
  
    // get option value
    var sortMethod = $(selector).multiselect('option', 'sortMethod');
    // set option after initialization (require refresh)
    $(selector).multiselect('option', 'sortMethod', _customSort).multiselect('refresh');
  

Methods

• refresh (argument: function) : refresh the multiselect widget. This method is useful if the SELECT element has been modified externally and changes needs to be applied to the widget. The refresh is done asynchronously and the callback function, if one provided, will be called once the refresh is complete.

    $(selector).multiselect('refresh', function() { /*...*/ });
  

• search (argument: string|object) : programmatically search the items. The arguments may be a string or an object to specify more options. Unless specified, all searches trigger a multiselectsearch event.

    // search for 'foo'
    $(selector).multiselect('search', 'foo');
    // search for 'foo' but do not trigger events
    $(selector).multiselect('search', {text: 'foo', silent:true});
    // search for 'foo' but do not toggle input field if hidden
    $(selector).multiselect('search', {text: 'foo', toggleInput:false});
  

• locale (argument: string) : set the widget's locale. The expected value is the same as the one in the locale init option. (Note : each multiselect instance may have their own locale.)

    // change the widget's locale to 'french'
    $(selector).multiselect('locale', 'fr');
  

Events

• multiselectChange : Event triggered after the selection has changed. The function will receive the usual event object, and a second argument, the ui object (ie. function(evt, ui)).

    $(selector).bind('multiselectChange', function(evt, ui) {
        // ui.optionElements: [JavaScript array of OPTION elements],
        // ui.selected: {true|false} if the optionsElements were just selected or not
    });
  

• multiselectSearch : Event triggered before the search filter is executed. This event make it possible to modify the search query without affecting the user text input field value. The function will receive the usual event object, and a second argument, the ui object (ie. function(evt, ui)).

    $(selector).bind('multiselectSearch', function(evt, ui) {
        // ui.text: {string|null} the search query, can be modified to change the search query
        // evt.preventDefault();   to cancel the search at this time
    });