#MSelectDBox - jQuery plugin for interactive dropdown lists.
Features
- Multiselect
- Events
- Autocomplete
- Custom function of autocomplete filter. Example: correction of keyboard language layout
- Could be attached to any target element
- Adapted for portable devices
- API propose the possibility to customize control (demo)
Demo
Download MSelectDialogBox.js
Download MSelectDBox.min.js
JSDoc documentation (detailed API)
Документация на русском
Example
$("#selector").mSelectDBox({ "list": (function(){ var arr = []; for(var c=0; c<30; c++){ arr.push(Math.round(Math.random() * 10000)); } return arr; })(), "multiple": false, "autoComplete": true, "name": "a" });
Constructor arguments
Passing as single object with keys:
- [Array]
list
- where list items may be key-value object with two string type properties{label:String(1),value:String(1)}
or string
Example:
var list = [ {"label": "Apple", "value": "0"}, {"label": "Orange", "value": "1"}, {"label": "Banana", "value": "2"} ];
Example:
var list = ["Apple", "Orange", "Banana"];
if need after initialization you can reassign the list by assigning a new array through a "set" method. Example:
$("#selector").mSelectDBox( "set", "list", [ "alpha", "beta", "gamma", "delta", "epsilon" ] );
-
[Boolean]
multiple
- enable or disable multiple selection of items in list. Default: false. -
[Boolean]
autoComplete
- enable or disable auto compelete. Only if target element is text input or textarea. Default: false. -
[String]
name
- name of instance. Used for search initialized instance by name. Default: undefined -
[Array]
optionFilters
- autocomplete filters. Default:[$.prototype.mSelectDBox.prototype.defaultOptionFilters.default]
-
[Boolean]
embeddedInput
- activates search input inside listbox -
[String]
width
- width of list box. Example:"10px"
or"auto"
-
[Number]
zIndex
-z-index
style property of list box -
[String]
language
- set language of instance (en | ru)
Events
-
init
- fires when instance initialized -
onselect
- fires when list item is selected -
onchange
- fires when text input was changed -
onkeydown
- same as original onkeydown event -
onkeyup
- same as original onkeyup event -
input:empty
- fires when text input become empty -
autocomplete:empty
- fires when autocomplete function results empty list -
autocomplete:not-empty
- fires when autocomplete function results not empty list -
focus
- you know... focus -
focusout
- same as blur -
set
- Fires when calling set method. Example: instance.set("fieldName", 100); -
set:field
- Fires when calling "set" method with specified key. Example: instance.set("field", 100); -
get
- Fires when calling "get" method. Example: instance.get("fieldName"); -
get:field
- Fires when calling "get" method with specified key. Example: instance.get("field", 100); -
afterSet:field
- Fires after "get" method was called with specified key. The event ensures that the function will be executed after the assignment and will have access to new value; -
beforeSet:field
- Fires before "get" method will be called with specified key.
Events may be attached in two ways:
Example:
$("#selector").mSelectDBox({ "list": [1,2,3], "onchange": function(msdbContext, event){ console.log(arguments); }, "onselect": function(msdbContext, event){ console.log(arguments); }, "input:empty": function(msdbContext, event){ console.log(arguments); } });
Example:
$("#selector").mSelectDBox({ "list": [1,2,3], "events": { "change": function(msdbContext, event){ console.log(arguments); }, "select": function(msdbContext, event){ console.log(arguments); }, "input:empty": function(msdbContext, event){ console.log(arguments); } } });
Autocomplete filters
Filter it's function. Part of autocomplete module. It compares each element of the list with the value of input. Returns true
if it meets the search condition,false
otherwise.
Example:
/** * @param {String} inputString * @param {String | Number} optionString */ function(inputString, optionString){ var pattern = new RegExp(inputString.trim(),"ig"); optionString = String(optionString); return Boolean(optionString.match(pattern)); }
Passing through constructor (param. "optionFilters"). Or may be added after initialization instance.get("optionFilters").push(function(matcherStr, matchedStr){...})
Filters available by default:
$.prototype.mSelectDBox.prototype.defaultOptionFilters.default
- default autocomplete filter$.prototype.mSelectDBox.prototype.defaultOptionFilters.russianKeyboard
- correcting layout to russian keyboard
Language support
Language of dropdown list can be assigned through constructor by using key language
If language is not specified, the library will try to determine language by user system settings
Predefined language codes:
- en - English
- ru - Russian
Example:
$("#selector").mSelectDBox({ "list": [1, 2, 3], "language": "en" // English });
To define or redefine a texts for a particular language, you can use the method setText
// Initialized instance $("#selector").mSelectDBox("setText", "Tap to close", ".m-select-d-box-fade__outside-click-label-text", "en");
the same to define new language support
// Initialized instance $("#selector").mSelectDBox("setText", "kapatmak için dokunun", ".m-select-d-box-fade__outside-click-label-text", "tr"); // Турецкий
Texts codes:
.m-select-d-box-fade__outside-click-label-text
- "Tap to close".m-select-d-box__search-input
- search input
Methods
.getInstances()
getInstances([Object] arg)
— search initialized instances by name. Return array of matched instances.
Example:
var dbox = $.prototype.mSelectDBox.prototype.getInstances({"name":"instanceName"});
Alternative:
var dbox = $("#selector").mSelectDBox();
The following methods can be called as an instance method or as a parameter to the method "mSelectDBox".
var dbox = $.prototype.mSelectDBox.prototype.getInstances({"name":"instanceName"})[0]; dbox.method(...);
.trigger()
trigger([String] eventName)
, .("trigger", [String] eventName)
— fire predefined event.
Example:
var dbox = $.prototype.mSelectDBox.prototype.getInstances({"name":"instanceName"})[0]; dbox.trigger("select");
Alternative:
$("#selector").mSelectDBox("trigger","select");
.on()
on([String] eventName, [Function] callback)
, .("on", [String] eventName, [Function] callback)
— add custom event listener.
Example:
var dbox = $.prototype.mSelectDBox.prototype.getInstances({"name":"instanceName"})[0]; dbox.on( "select", function(msdbContext, event){ console.log(arguments); } );
Alternative:
$("#selector").mSelectDBox( "on", "select", function(msdbContext, event){ console.log(arguments); } );
.select()
select([Object] arg)
,.("select", [Object] arg)
— select list options by value, label or id (key)
arg = {"label": Array | String};
or
arg = {"value": Array | String};
Example:
var dbox = $.prototype.mSelectDBox.prototype.getInstances({"name":"instanceName"})[0]; dbox.select({"label": ["100", "200"]}); dbox.select({"label": "100"}); dbox.select({"value": "0"});
Alternative:
$("#selector").mSelectDBox("select",{"label": ["100", "200"]});
.getSelectedLabels()
Return array of selected list labels
var array = $("#selector").mSelectDBox("getSelectedLabels");
Alternative:
var array = $("#selector").mSelectDBox().getSelectedLabels();
.getSelectedValues()
Return array of selected list values
var array = $("#selector").mSelectDBox("getSelectedValues");
Alternative:
var array = $("#selector").mSelectDBox().getSelectedValues();
.selectAll()
selectAll(void)
— select all list options. Only if multiple = true
.deselectAll()
deselectAll(void)
.open()
open(void)
— show list box
.close()
close(void)
— hide list box
.isActive()
isActive(void)
— return true if list box is visible
.get()
get([String] key)
— returns property of MSelectDBox instance
.set()
set([String] key, [Any] value)
— set new or update property of MSelectDBox instance
TODO
- Groups
- README.MD