Settings

Plugin settings are set during the initialization time.

$("select#demo").smartselect({
    multiple: false
});
name description

multiple

type: boolean
default: true 		Set the plugin to multiple select. Normally this setting will be automatically generated from the original <SELECT> by looking at its attribute multiple.

optimized

type: boolean
default: false 		Set the plugin to optimized mode, which means delayedInit: true, debug: 0, keepInSync: false

delayedInit

type: boolean
default: true 		Delay partial of the initialization process to first dropdown. This will decrease plugin load time up to 20%.

debug

type: integer
default: 0 		Debug switch to pring debug messages in console. Set to 1 to enable debugging.

debugLevel

type: integer
default: 5 		Debug level 2 - 9. Set to 9 if the detailed messages wanted.

maxLevels

type: integer
default: 5 		Maximum data levels allowed. There is no hard limit on the data-level. If you want to support more than the default 5 levels, you may set here and also modify the data-level related style in the 'smartselect.css' file.

closeOnSelect

type: boolean
default: false 		Close the dropdown automatically once click/select an option. This option is set to TRUE automatically in single select situation.

closeOtherSmartSelect

type: boolean
default: true 		If set to TRUE, close other smartselects' dropdowns when open this plugin's dropdown.

defaultValues

type: array
default: null 		array of values (string). When all options deselected, plugin will reset to these default values.

initialValues

type: array
default: [] 		array of values (string). Initial options to select, similar to the original <SELECT> has values selected.

keepInSync

type: boolean
default: true 		If set to TRUE, will always keep the original <SELECT> in sync with plugin. In optimized mode, this switch is set to FALSE to increase performance. and the sync will be performed when dropdown closed or by calling method 'syncSelect' manually.

clickGroupOpen

type: boolean
default: true 		If set to TRUE, click the group label will expand the group.

showSelectedInLabel

type: boolean
default: true 		If set to TRUE, display option labels/text in the plugin button.

showSelectedCount

type: integer
default: 2 		Max number of selected option text to display

showSelectedSeperator

type: string
default: ', ' 		seperator used in displaying option text

defaultView

type: string
default: 'root+selected' 		Default fold/unfold view for the first time dropdown. possible values are 'root', 'expand', 'level1', 'level2' and 'selected'. 'selected' can be combined with other values like 'root+selected'.

viewAfterCheckAll

type: boolean
default: true 		Simulate a click of the buttonView after clicking buttonCheckAll

viewAfterCancel

type: boolean
default: true 		Simulate a click of the buttonView after clicking buttonCancel

viewAfterAlias

type: boolean
default: true 		Simulate a click of the buttonView after selecting an alias

closeAfterAlias

type: boolean
default: true 		Close the dropdown after selecting an alias.

searchBy

type: string
default: 'label' 		The search field. possible values are 'label', 'value' and 'both'

searchCaseInsensitive

type: boolean
default: true 		search case-insensitive

atLeast

type: integer
default: 0 		number of selected options required.

atMost

type: integer
default: 0 		max number of selected options allowed, 0 is no limit.

mustSelect

type: array
default: [] 		must selected options in array of values. Attribute 'data-must' for <OPTION> will achieve the same result.

data

type: array
default: [] 		Instead of attach to a <SELECT>. User may provide option data here. the format is the same as 'addOption()'.

aliases

type: object
default: {} 		Initialize the aliases. 
aliases: {
    'test 1': [ '2', '3' ],
    'test 2': [ '1', '5', '7']
}

Toolbar

Swithes for toolbar buttons

$("select#demo").smartselect({
    toolbar: {
        buttonCancel: false
    }
});
name description

buttonSearch

type: boolean
default: true 		Search the options.

buttonAlias

type: boolean
default: true 		Alias related functionalities.

buttonView

type: string
default: 'root+selected' 		Set current fold/unfold viewing status by click buttonView. Possible values are same as 'defaultView'

buttonUnfold

type: boolean
default: true 		Unfold all.

buttonCancel

type: boolean
default: true 		Cancel current selections, revert to the state of before dropdown shows.

buttonCheckAll

type: boolean
default: true 		Select all.

buttonUnCheck

type: boolean
default: true 		Deselect all.

APIs

APIs detail

var ss = $("select#demo").smartselect().getsmartselect();
ss.selectOptions([ '4', '6' ]);
name description

smartselect(options, extra)

param: {Object} options
param: {Object} extra
returns: jQuery 		Initialize the plugin

getsmartselect()

returns: SmartSelect 		Get the smartselect object.

selectOptions(values, clear)

param: {Array} values
param: {Boolean} clear, default to TRUE
returns: SmartSelect 		Select options base on the values provided. By default, clear all first.

deselectOptions(values)

param: {Array} values
returns: SmartSelect 		Deselect options base on the values provided.

getValues()

returns: Array 		Get selected values in array

isDisabled()

returns: Boolean 		Is the plugin disabled ?

disableSelect()

returns: SmartSelect 		disable the plugin

enableSelect()

returns: SmartSelect 		enable the plugin

disableOptions(values)

param: {Array} values
returns: SmartSelect 		Disable options base on given values

enableOptions(values)

param: {Array} values
returns: SmartSelect 		Enable options base on given values

addOption(info, after, parent)

param: {Object} info
param: {ValueString, HTHMLElement, jQuery, IDstring} after
param: {ValueString, HTHMLElement, jQuery, IDstring} parent
returns: SmartSelect 		Add an option to the plugin. Properties 'info.label' and 'info.value' are required. Other properties: 'info.data-level', 'info.data-must', 'info.data-view' etc. 'after' is an option to add after. 'parent' is an option or group to add under.

removeOption(value)

param: {String} value
returns: SmartSelect 		Remove an option by value

getGroup(name)

param: {String|jQuery} name
returns: jQuery 		Get group object base on the given name to match

getSelectedPairs()

returns: Object 		Get selected options. The result object $res has {Array} $res.value and {Object} $res.label

toggleDropdown(hideDropdown)

param: {Boolean} hideDropdown
returns: SmartSelect 		Toggle dropdown. 'hideDropdown' TRUE force hide, FALSE force open

toggleOption(li, triggerChange, setOption)

param: {ValueString, HTHMLElement, jQuery, IDstring} li
param: {Boolean} triggerChange
param: {Boolean} setOption
returns: SmartSelect 		Select or deselect an option. 'triggerChange' set FALSE to disable. 'setOption' TRUE force select, FALSE force deselect.

selectOption(li, triggerChange)

param: {ValueString, HTHMLElement, jQuery, IDstring} li
param: {Boolean} triggerChange
returns: SmartSelect 		Select an option. 'triggerChange' set FALSE to disable.

deselectOption(li, triggerChange)

param: {ValueString, HTHMLElement, jQuery, IDstring} li
param: {Boolean} triggerChange
returns: SmartSelect 		Deselect an option. 'triggerChange' set FALSE to disable.

addCallback(event, callback)

param: {String} event
param: {Callback, Array} callback
returns: SmartSelect 		Add a callback for procedural event. May take an array of callbacks.

selectAllOptions()

returns: SmartSelect 		Select all options

deselectAllOptions()

returns: SmartSelect 		Deselect all options

selectGroupOptions($group, triggerChange)

param: {String, jQuery} $group
param: {Boolean} triggerChange
returns: SmartSelect 		Select all options in a group. $group is a group name or jquery object. If $group is undefined, select all options under the root.

deselectGroupOptions($group, triggerChange)

param: {String, jQuery} $group
param: {Boolean} triggerChange
returns: SmartSelect 		Deselect all options in a group. $group is a group name or jquery object. If $group is undefined, select all options under the root.

addAlias(name, value, syncLabel, syncAlias)

param: {String, Object} name
param: {Array} value
param: {Boolean} syncLabel
param: {Boolean} syncAlias
returns: SmartSelect 		Add one alias or a group of aliases.

removeAlias(name, syncLabel, syncAlias)

param: {String, Array} name
param: {Boolean} syncLabel
param: {Boolean} syncAlias
returns: SmartSelect 		Remove one alias or a group of aliases.

selectAlias(name)

param: {String} name
returns: SmartSelect 		Click one alias.

syncSelect()

returns: SmartSelect 		Force sync with original <SELECT>

Callbacks

Procedural events related callbacks can be defined initially or added later by api 'addCallback()'. Procedural event callbacks must return a boolean value to indicate wether success or not. Procedural event callbacks WILL affect the plugin behavior.

var ss = $("select#demo").smartselect({
    callback: {
        onPluginLoad: [ myCallback, myCallback2 ]
    }
}).getsmartselect();

ss.addCallback('onDropdownShown', myCallback3);
name description

onPluginLoad

 Just before plugin init.

onPluginLoaded

 Right after plugin finished init.

onDropdownShow

 Right before dropdown show.

onDropdownShown

 Right after dropdown shown.

onDropdownHide

 Right before dropdown hide.

onDropdownHidden

 Right after dropdown hidden.

onOptionChange

 Right before change option(s).

onOptionChanged

 Right after option(s) changed.

onOptionDisable

 Right before disable an option.

onOptionDisabled

 Right after option(s) disabled.

onOptionSelect

 Right before select an option.

onOptionSelected

 Right after option selected.

onOptionDeselect

 Right before deselect an option.

onOptionDeselected

 Right after option deselected.

Handlers

Status change events can have handlers defined to listen to these events. These handlers will NOT affect plugin behavior

$("select#demo").smartselect({
    atLeast: 2,
    atMost: 4,
    mustSelect: [ '1' ],
    handler: {
        atLeast: function() { alert('at least 2 options required');},
        atMost: function() { alert('maximum 4 options exceeded');},
        mustSelect: function() { alert('must select this one');}
    }
});
name description

optionDuplicated

 Triggered in addOption() if duplicated option found.

optionAdded

 Triggered in addOption() after option added.

optionRemoved

 Triggered in removeOption() after option removed.

aliasChange

 Triggered after alias added or removed.

atLeast

 Triggered when deselect an option.

mustSelect

 Triggered when deselect an option.

atMost

 Triggered when select an option

Attributes

Predefined attributes can be added to <SELECT>, <OPTGROUP> and <OPTION> to achieve complex functionalities.

name description

data-view

 Can be applied to <OPTGROUP> or <OPTION>. Takes an integer value 'N' or no value (equals to 1). Means expand 'N' level below current group or option.

data-must

 Can be applied to <OPTION>. Takes no value. Means this option has to be selected.

data-level

 Can be applied to <OPTION>. Takes an integer value 'N'. Indicates the current level of this option.

data-atmost

 Can be applied to <SELECT> or <OPTGROUP>. Takes an integer value 'N'. Indicates the maximum number of selected options allowed.

data-divider

 Can be applied to <OPTION>. Takes no value. Indicates this is a divider.

data-atleast

 Can be applied to <SELECT> or <OPTGROUP>. Takes an integer value 'N'. Indicates the minimum number of selected options required.

data-exclusive

 Can be applied to <SELECT> or <OPTGROUP>. Takes no value. Indicates options exclusive with others.

data-inclusive

 Can be applied to <OPTION>. Takes space seperated string value like 'a b c'. Options with same char can be selected together (inclusive).

data-group-exclusive

 Can be applied to <OPTGROUP>. Takes space seperated string value like 'a b c' or no value (means '_'). Groups with same char may have options selected at the same time, but others not (exclusive).