See examples here.
Options | |||
---|---|---|---|
Property | Type | Description | Default |
data | Array, Object, String |
The data for filling combobox items. The original select is used for retrieving data if no data param was given.
The data my be an array or an object with enumerated properties that is {0: {...}, 1: {...}} . Also data can be
supplied as JSON string. Each item in data except headers and separators (elements having separator property)
must contain value property, which is an equivalent of option tag value in select. The text of an item should
be stored in text property. If the item has a separator property then it appears as a separator
in the list. If it also has a header (a string supposed) property then it appears as a header in the list.
Be sure a header item has a text anyway if you use data sorting to control its position because sorting depends on text.
To use data option in a more flexible way see pMarkup and pFillFunc options.
|
null |
empty | Boolean | Whether combobox is empty by default (true) or has an original select value (usually it the first value,
but can be changed by added a selected prop). |
false |
disabled | Boolean | Whether to set a visible text input disabled or not. | false |
sort | Boolean | Whether to sort data. Sorting depends on text. | true |
sortAsc | Boolean | Whether to sort ascending (true) or descending (false). | true |
removeDuplicates | Boolean | Whether to remove duplicates from given date. Duplicates are considered as elements with the same value properties. |
true |
fullMatch | Boolean | Whether to filter the items not only from the beginning of the line. Anyhow, the filtering is applied only in text stored inside of
<span class="scombobox-mainspan"></span> element. See also pMarkup and pFillFunc |
false |
highlight | Boolean, null | Whether to highlight matches in items while filtering. By default highlighting is enabled if fullMatch is enabled
(highlight is set to null by default). To use fullMatch without highlighting set highlight option
strictly to false . To turn on highlighting anyway set it to true . |
null |
filterIgnoreCase | Boolean | Whether to search ignoring case. | true |
filterIgnoreAccents | Boolean | Whether to convert a needle and a haystack like 'Cajicá' or 'Hősök' to 'Cajica' and 'Hosok'. | false |
filterDelay | Number | Whether to debounce search function, falsy value for no debounce. | 0 |
hideSeparatorsOnSearch | Boolean | Whether to exclude separators from the match list that appears when typing into the filter input. | false |
expandOnFocus | Boolean | Whether to expand combobox on focus in filter input. Applies on an empty combobox. | true |
expandOnFocusWithValue | Boolean | Whether to expand combobox on focus in filter input. Applies on a filled combobox. | true |
wrap | Boolean | Whether to use word wrap in items. | true |
fillOnArrowPress | Boolean | Whether to change the text in filter input while walking up and down by arrows. If this option is turned off than text changes only
on blur (if fillOnBlur is on). |
true |
fillOnBlur | Boolean | Whether to change combobox value on blur. In this case the current selected item will be used. This feature works when using arrow keys. | false |
blurOnEscape | Boolean | Whether to leave the search input focus on escape keypress or not. | false |
fillOnTab | Boolean | Whether to set the first visible item as a value on tab key press. If set to false then the default action is working (going to the next input on page). | true |
showDropDown | Boolean | Whether to display an arrow button in the right corner of a combobox. | true |
forbidInvalid | Boolean | Whether to forbid leaving invalid value in combobox on blur. In case this feature is disabled combobox is highlighted on blur
(scombobox-invalid css-class). Other way, the filter text field becomes empty and the combobox value is unset.
|
false |
invalidAsValue | Boolean | When true, then value from visible input will be a value of the combobox (returned by $(combo).scombobox('val') ).
|
false |
highlightInvalid | Boolean, null | When true, the combobox is marked with red (.scombobox-invalid CSS class) when there is an invalid value.
If invalidAsValue is set to true then highlightInvalid is considered false by default.
If you want to enabled or disable it regardless to invalidAsValue set it to a any truthy value or not null
falsy value correspondingly.
|
false |
maxHeight | String | Sets the items list div max height (css property). | '' |
tabindex | Number, null | This field sets tabindex for current combobox or set of comboboxes. If set to null, tabindex is removed. | null |
placeholder | String | This field sets placeholder html attribute for search input. | null |
reassignId | Boolean | Whether to reattach the id from original select to created combobox. |
true |
mode | String | Whether to use 'default' or 'checkboxes' mode of combobox. 'default' mode is a regular select with a search
field. 'checkboxes' is a mode when you can select multiple items by clicking checkboxes in it. In this mode you don't have a text field
for search and the value of combobox is an array of strings – selected values, not the single string. |
'default' |
pMarkup | String | The paragraph markup. Each item in a list is a paragraph tag. You can provide your own properties
and use it your own way in pFullFunc . You can use boolean selected property to
define whether this option is selected by default. In case of single-value combo the last selected
option value will be used. |
'<img src="${imgsrc}" /><span class="scombobox-mainspan">${text}</span> <span>${additional}</span>' |
pFillFunc | Function | Function which fills the items using provided data and pMarkup option. |
function(item, options) { var $p = $('<p />').html(options.pMarkup .replace('${text}', item.text) .replace('${additional}', item.additional ? item.additional : '') .replace('${imgsrc}', item.imgsrc || '') ); if (typeof item.imgsrc != 'string') { $p.find('img').hide(); } return $p; } |
autoLoad | Function | This option is for ajax loading (appending/prepending items). The usage is following:
function(value, direction) { // value here is the edge value in the list (last for appending or first for prepending). // direction here is the scrolling direction, which can be either 'top' or 'bottom' // so you can do something like this: var $t = this; $.post('your url here' + (direction == 'top' ? '?prepend' : ''), {id: value}, function(res) { $t.scombobox('fill', res, direction == 'top' ? 2 : 1); // 1 for prepending, 2 for appending $t.data('pending', false); // this line is compulsory }, 'json'); } |
$.noop |
animation | Object | Animation options (combobox opening/closing). | { duration: 'fast', easing: 'swing' } |
listMaxWidth | Number | Limits the list with paragraphs width. | window.screen.width / 2 |
callback | Object | callback.func executes with arguments callback.args
after every combobox initialization finished. If the target set
contains multiple comboboxes, than callback executes each time. this refers
to the main combobox div (class scombobox ). |
{ func: $.noop, // this refers to combobox's div holder args: [] // arguments } |
beforeOpen | Function | This event fires just before div with options slides down.
this refers to <div class="scombobox"></div>
|
$.noop |
beforeClose | Function | This event fires just before div with options slides up.
this refers to <div class="scombobox"></div>
|
$.noop |
afterOpen | Function | This event fires just after div with options slides down.
this refers to <div class="scombobox"></div>
|
$.noop |
afterClose | Function | This event fires just after div with options slides up.
this refers to <div class="scombobox"></div>
|
$.noop |
Methods | |||
Title | Arguments | Description | Returns |
fill | data {Array|Object|String|undefined} data, appendMode {Number} flag | Sets the combobox data. The data may be represented in the same way as data option.
Use appendMode option to append or prepend items instead of overwriting all existing ones.
When using this argument 1 stands for appending and 2 for prepending.
Despite of having options method described below, this method is useful because
after using options method the data will be merged what may be undesired.
|
jQuery instance | combobox data |
clear | Empties the combobox. You can still use fill method to get the combobox items back. |
jQuery instance |
|
disabled | b {Boolean|undefined} flag | disabled property getter and setter. |
disabled status | jQuery instance |
placeholder | {String|undefined} text | placeholder property getter and setter. |
placeholder text | jQuery instance |
options | options {Object|undefined} | Instance options getter and setter. | instance options | jQuery instance |
val | value {String|Array} | Combobox value getter and setter. For 'default' mode use string, for 'checkboxes' use array of strings. |
Combobox value | jQuery instance |
open | Drops the list down. | jQuery instance |
|
close | Closes the list up. | jQuery instance |
|
toSelect | Destroys the combobox, keeping only an original select. Returns a jQuery object with a select. | jQuery instance |
|
Here are methods which help with working with listeners. To add a listener, use
$(combobox).scombobox('listener', function(){}) syntax. this will refer to different elements depending on event type.
To trigger an event use $(combobox).scombobox('listener') syntax; to trigger event with a certain namespace, use
$(combobox).scombobox('listener', 'namespace') syntax. |
|||
Event type | this | Description | |
change | select | On select change (hidden element). | |
focus | <input class="scombobox-display" /> | On filter input focus. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field.td> | |
blur | <input class="scombobox-display" /> | On filter input blur. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field. | |
keyup | <input class="scombobox-display" /> | On filter input keyup. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field. | |
keydown | <input class="scombobox-display" /> | On filter input keydown. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field. | |
keypress | <input class="scombobox-display" /> | On filter input keypress. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field. | |
click | <input class="scombobox-display" /> | On filter input click. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field. | |
mousedown | <input class="scombobox-display" /> | On filter input mousedown. This event does not matter when using 'checkboxes' mode, because this combobox does not have such text field. | |
clickDropdown | <div class="scombobox-list" /> | This event is a click on the dropdown button located in the right corner of a combobox. |