diff --git a/docs/index.html b/docs/index.html index 4b27672..e82c0a1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,649 +1,655 @@ - - - - - - - - - - - - - - - - - - - - - Jquery.sumoselect by Hemant Negi - - - - -
-
- -

Jquery.sumoselect

- -

A beautiful jQuery Single/Multi Select plugin which can be used on almost any device

- - View project on - GitHub -
-
- -
-
-
-
- - - - -
-

- jquery.sumoselect -

- -

- jquery.sumoselect.js - A cross device Single/Multi Select jQuery - Select plugin.

- -

LIVE DEMO HERE - -

Sumoselect full : jquery.sumoselect.js - - -

Minified : jquery.sumoselect.min.js - - -

- A jQuery plugin that progressively enhances an HTML Select Box into a Single/Multiple option dropdown list. The - dropdown list can be fully customiseable using siple css properties. - It can adapt itself according to any deveice, keeping in mind that the User Experience is not broken. - - -

Notable Features - -

    -
  • - Single and Multi select option. -
    • -
  • - Search Support -
    • -
  • - Optgroup support. -
    • -
  • - Localization support. -
    • -
  • - Fully customizable by simple css. -
    • -
  • - Supports almost all devices (Till now i didnt found one) -
    • -
  • - Intelligently Renders itself according to the devices. -
    • -
  • - Renders native Single/Multiple pop up on Android, ios, Windows and other devices. -
    • -
  • - Custom postback data format (Multiple select data can be passed either as csv or default select) -
    • -
  • - Selected, Disabled, Select All, keyboard navigation and Placeholder Support -
    • -
  • - Redesigned the UI (No external icons are used now and color scheme can be controlled by css) -
    • -
  • - Easily extendable to allow developers to create new widgets -
    • -
  • - Basic methods to handle all kinds of manipulations like adding item, remove item, disable, select etc. -
    • -
-

- Requirements -

- -

jQuery 1.8.3+ (It is always recommended to use the latest version of jQuery) - -

- Desktop Browser Support

- -

IE8+, Firefox 4+, Chrome, Safari 4+, Opera 11+ (Other browsers may work, but I did not test on them) - -

- Mobile/Tablet Browser Support

- -

iOs 3+, Android 2.1+ , Windows Mobile (Other browsers may work, but I did not test on them) - -

- Forking

- -

If you find that you need a feature that SumoSelect does not currently support, either let me know via the SumoSelect - issue tracker, or fork SumoSelect on Github and easily extend SumoSelect to create your own widget! - -

- Usage

- -

To just go with the default options simply do - -

- 
 $(document).ready(function () {
-            $('.SlectBox').SumoSelect();
-     });
-
-
- -

To provide optional settings, simply pass settings object to SumoSelect() - -

- 
 $(document).ready(function () {
-            $('.SlectBox').SumoSelect({
-			placeholder: 'This is a placeholder',
-			csvDispCount: 3 
-			});
-        });
-
-
- -

Settings - -

The following settings are available now: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OptionTypeDiscription
placeholder(string)The palceholder text to be displayed in the rendered select widget (on priority basis). *Maximum priority is - given to native placeholder attribute in select tag i.e. - <select placeholder="this is a - placeholder" /> - Then the option with disabled and selected attribute i.e. <option - disabled selected value="foo" > - Last to to the given placeholder attribute in the settings. - * -
csvDispCount(int)The number of items to be displayed in the widget seperated by a , after that the text will be - warped as 3+ Selected. Set 0 for all the options. -
captionFormat(string)Its the format in which you want to see the caption when more than csvDispCount items are selected. its - default value is'{0} Selected' ( here {0} will be replaced by the seletion count ) -
captionFormatAllSelected(string)I Format of caption text when all elements are selected. set null to use captionFormat. It will not work if - there are disabled elements in select. default is '{0} all selected!' -
floatWidth(int)Minimum screen width of device below which the options list is rendered in floating popup fashion.
forceCustomRendering(boolean) Force the custom modal ( Floating list ) on all devices below floatWidth resolution.
nativeOnDevice(Array[string])The keywords to identify a mobile device from useragent string. The system default select list is rendered - on the matched device. -
outputAsCSV(boolean)true to POST data as csv ( false for deafault select )
csvSepChar(string)Seperation char if outputAsCSV is set to true
okCancelInMulti(boolean)Displays Ok Cancel buttons in desktop mode multiselect also.
isClickAwayOk(boolean)for okCancelInMulti=true. sets whether click outside will trigger Ok or Cancel (default is cancel).
triggerChangeCombined(boolean)In Multiselect mode whether to trigger change event on individual selection of each item or on combined - selection ( pressing of OK or Cancel button ). -
selectAll(boolean)To display select all check or not
search(boolean)To enable searching in sumoselect (default is false).
searchText(string)placeholder for search input.
searchFn(function)Custom search function.
noMatch(string)placeholder to display if no itmes matches the search term (default 'No matches for "{0}"').
prefix(string)prefix to prepend the selected text (default is empty) eg. '<b>Hello</b>'.
locale(array)change the text used in plugin (['OK', 'Cancel', 'Select All']). Note: don't break the sequence or skip items.
up(boolean)the direction in which to open the dropdown (default: false)
showTitle(boolean)set to false to prevent title (tooltip) from appearing (deafult: true)
max(int)Maximum number of selected options (if multiple)
renderLi(function)Custom <li> item renderer.
- -

- -
- The default settings are : - - -

- 
{
-    placeholder: 'Select Here',
-    csvDispCount: 3,
-    captionFormat: '{0} Selected',
-    captionFormatAllSelected: ''{0} all selected!'',
-    floatWidth: 500,
-    forceCustomRendering: false,
-    nativeOnDevice: ['Android', 'BlackBerry', 'iPhone', 'iPad', 'iPod', 'Opera Mini', 'IEMobile', 'Silk'],
-    outputAsCSV : false,
-    csvSepChar : ',', 
-    okCancelInMulti: true, 
-    isClickAwayOk: false,
-    triggerChangeCombined : true,
-    selectAll : false,
-    search : false,
-    searchText : 'Search...',
-    searchFn : function(haystack, needle, el){ ... },
-    noMatch : 'No matches for "{0}"',
-    prefix : '',
-    locale :  ['OK', 'Cancel', 'Select All'],
-    up : 'false',
-    showTitle : 'true',
-    max : null,
-    renderLi : (li, originalOption) => li,
-}
-
-
- -

Events

-

Sumoselect raise some very helpful events on which you can hook your custom handlers.

- - 
-$('select.SlectBox').on('sumo:opened', function(sumo) {
-    // Do stuff here
-    console.log("Drop down opened", sumo)
-});
-
-

- Available events -

- 
-// Drop down initialized.
-sumo:initialized
-// Drop down opening
-sumo:opening
-// Drop down opened
-sumo:opened
-// Drop down closing
-sumo:closing
-// Drop down closed.
-sumo:closed
-// Drop down unloaded.
-sumo:unloaded
-
-

Methods

- -

To call below functions you need to get the instance of SumoSelect object which can be done as - -

- 
 var MySelect;
-$(document).ready(function () {
-            MySelect = $('.SlectBox').SumoSelect();
-     });
-
-
- -

Or simply you can get the instance from select element directly i.e. - -

- 
 var MySelect = $('select.SlectBox')[0].sumo;
-
- -

Note : The SumoSelect object is directly binded with native select element not with the jquery object of - element. - -

Following is the list of methods of SumoSelect. -

    -
  • - .unload() - -

    Deactivate the SumoSelect plugin and display original select element. ( You can reinitialize the SumoSelect - for this select. ) - -

    - 
     $('select.SlectBox')[0].sumo.unload();
    -
    - -
    • -
  • - .add(value [,text][,index][,attrs]) - -

    Insert an new item in the select at a given index if index is provided else added to last. use index 0 to - insert at the begining. - -

    - 
    // adds a option with value and html set to 'india' at the last.
-$('select.SlectBox')[0].sumo.add('india');
-
-// adds a option with value and html set to 'india' at index no 3.
-$('select.SlectBox')[0].sumo.add('india',3);
-
-// adds a option with value = 'india' and html = 'Indian' at the last.
-$('select.SlectBox')[0].sumo.add('india','Indian');
-
-// adds a option with value and html set to 'india' at index no 0.
-$('select.SlectBox')[0].sumo.add('india','Indian',0);
    -// adds a option with value and html set to 'india' at index no 0 with some attributes. -$('select.SlectBox')[0].sumo.add('india','Indian',0, {'data-test': 'test'}); -
    - -
    • -
  • - .remove(index) - -

    Removes an item from a given index number. - -

    - 
     $('select.SlectBox')[0].sumo.remove(2);
    -
    - -
    • -
  • - .selectItem(index/value) - -

    Selects (check an item) an item in the list by index or by its value. You can select multiple items in case of a multiselect. - -

    - 
    //selects the item at index 2
- $('select.SlectBox')[0].sumo.selectItem(2);
- //selects the item having value "volo"
- $('select.SlectBox')[0].sumo.selectItem('volo');
    -
    - -
    • -
  • - .unSelectItem(index/value) - -

    unselect (uncheck an item) an item in list by index or by value - -

    - 
    //unselects the item at index 2
- $('select.SlectBox')[0].sumo.unSelectItem(2);
- //unselects the item having value "volvo"
- $('select.SlectBox')[0].sumo.unSelectItem('volvo');
    -
    - -
    • -
  • - .disableItem(index) - -

    Disables and item in the list - -

    - 
    //disables the item at index 2
- $('select.SlectBox')[0].sumo.disableItem(2);
    -
    - -
    • -
  • - .enableItem(index) - -

    Enables and item in the list - -

    - 
    //enables the item at index 2
- $('select.SlectBox')[0].sumo.enableItem(2);
    -
    - -
    • -
  • - .selectAll() - -

    Selects all items list - -

    - 
    //selects all items (excluding disabled)
- $('select.SlectBox')[0].sumo.selectAll();
    -
    - -
    • -
  • - .unSelectAll() - -

    Un selects all items in the list - -

    - 
    //Un select all items
- $('select.SlectBox')[0].sumo.unSelectAll();
    -
    - -
    • -
  • - .enable() -

    Enables the SumoSelect control -

    - 
    $('select.SlectBox')[0].sumo.enable();
    -
    -
    • -
  • - .disable() -

    Disable the SumoSelect control -

    - 
    $('select.SlectBox')[0].sumo.disable();
    -
    -
    • -
  • - .unSelectAll() -

    Un selects all items in the list -

    - 
    //Un select all items
-$('select.SlectBox')[0].sumo.unSelectAll();
    -
    -
    • -
  • - .reload() -

    This method reloads the UI over original select element. so now you can perform the desired operations on underlying select element and then update the UI od sumoselct after that. -

    - 
    //Reloads the UI of plugin.
-$('select.SlectBox')[0].sumo.reload();
    -
    -
    • - - -
- -

*** You can add custom css class to options (css class added to option is added to the generated li.) - -

- License

- -

Copyright (c) 2014 Hemant Negi Licensed under the MIT license. -

- - -
-
- - - - + + + + + + + + + + + + + + + + + + + + + Jquery.sumoselect by Hemant Negi + + + + +
+
+ +

Jquery.sumoselect

+ +

A beautiful jQuery Single/Multi Select plugin which can be used on almost any device

+ + View project on + GitHub +
+
+ +
+
+
+
+ + + + +
+

+ jquery.sumoselect +

+ +

+ jquery.sumoselect.js - A cross device Single/Multi Select jQuery + Select plugin.

+ +

LIVE DEMO HERE + +

Sumoselect full : jquery.sumoselect.js + + +

Minified : jquery.sumoselect.min.js + + +

+ A jQuery plugin that progressively enhances an HTML Select Box into a Single/Multiple option dropdown list. The + dropdown list can be fully customiseable using siple css properties. + It can adapt itself according to any deveice, keeping in mind that the User Experience is not broken. + + +

Notable Features + +

    +
  • + Single and Multi select option. +
    • +
  • + Search Support +
    • +
  • + Optgroup support. +
    • +
  • + Localization support. +
    • +
  • + Fully customizable by simple css. +
    • +
  • + Supports almost all devices (Till now i didnt found one) +
    • +
  • + Intelligently Renders itself according to the devices. +
    • +
  • + Renders native Single/Multiple pop up on Android, ios, Windows and other devices. +
    • +
  • + Custom postback data format (Multiple select data can be passed either as csv or default select) +
    • +
  • + Selected, Disabled, Select All, keyboard navigation and Placeholder Support +
    • +
  • + Redesigned the UI (No external icons are used now and color scheme can be controlled by css) +
    • +
  • + Easily extendable to allow developers to create new widgets +
    • +
  • + Basic methods to handle all kinds of manipulations like adding item, remove item, disable, select etc. +
    • +
+

+ Requirements +

+ +

jQuery 1.8.3+ (It is always recommended to use the latest version of jQuery) + +

+ Desktop Browser Support

+ +

IE8+, Firefox 4+, Chrome, Safari 4+, Opera 11+ (Other browsers may work, but I did not test on them) + +

+ Mobile/Tablet Browser Support

+ +

iOs 3+, Android 2.1+ , Windows Mobile (Other browsers may work, but I did not test on them) + +

+ Forking

+ +

If you find that you need a feature that SumoSelect does not currently support, either let me know via the SumoSelect + issue tracker, or fork SumoSelect on Github and easily extend SumoSelect to create your own widget! + +

+ Usage

+ +

To just go with the default options simply do + +

+ 
 $(document).ready(function () {
+            $('.SlectBox').SumoSelect();
+     });
+
+
+ +

To provide optional settings, simply pass settings object to SumoSelect() + +

+ 
 $(document).ready(function () {
+            $('.SlectBox').SumoSelect({
+			placeholder: 'This is a placeholder',
+			csvDispCount: 3 
+			});
+        });
+
+
+ +

Settings + +

The following settings are available now: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionTypeDiscription
placeholder(string)The palceholder text to be displayed in the rendered select widget (on priority basis). *Maximum priority is + given to native placeholder attribute in select tag i.e. - <select placeholder="this is a + placeholder" /> - Then the option with disabled and selected attribute i.e. <option + disabled selected value="foo" > - Last to to the given placeholder attribute in the settings. + * +
csvDispCount(int)The number of items to be displayed in the widget seperated by a , after that the text will be + warped as 3+ Selected. Set 0 for all the options. +
captionFormat(string)Its the format in which you want to see the caption when more than csvDispCount items are selected. its + default value is'{0} Selected' ( here {0} will be replaced by the seletion count ) +
captionFormatAllSelected(string)I Format of caption text when all elements are selected. set null to use captionFormat. It will not work if + there are disabled elements in select. default is '{0} all selected!' +
floatWidth(int)Minimum screen width of device below which the options list is rendered in floating popup fashion.
forceCustomRendering(boolean) Force the custom modal ( Floating list ) on all devices below floatWidth resolution.
nativeOnDevice(Array[string])The keywords to identify a mobile device from useragent string. The system default select list is rendered + on the matched device. +
outputAsCSV(boolean)true to POST data as csv ( false for deafault select )
csvSepChar(string)Seperation char if outputAsCSV is set to true
okCancelInMulti(boolean)Displays Ok Cancel buttons in desktop mode multiselect also.
isClickAwayOk(boolean)for okCancelInMulti=true. sets whether click outside will trigger Ok or Cancel (default is cancel).
triggerChangeCombined(boolean)In Multiselect mode whether to trigger change event on individual selection of each item or on combined + selection ( pressing of OK or Cancel button ). +
selectAll(boolean)To display select all check or not (default is false).
selectAllPartialCheck(boolean)Display a disabled checkbox in multiselect mode when all the items are not selected (default is true).
search(boolean)To enable searching in sumoselect (default is false).
searchText(string)placeholder for search input.
searchFn(function)Custom search function.
noMatch(string)placeholder to display if no itmes matches the search term (default 'No matches for "{0}"').
prefix(string)prefix to prepend the selected text (default is empty) eg. '<b>Hello</b>'.
locale(array)change the text used in plugin (['OK', 'Cancel', 'Select All']). Note: don't break the sequence or skip items.
up(boolean)the direction in which to open the dropdown (default: false)
showTitle(boolean)set to false to prevent title (tooltip) from appearing (deafult: true)
max(int)Maximum number of selected options (if multiple)
renderLi(function)Custom <li> item renderer.
+ +

+ +
+ The default settings are : + + +

+ 
{
+    placeholder: 'Select Here',
+    csvDispCount: 3,
+    captionFormat: '{0} Selected',
+    captionFormatAllSelected: ''{0} all selected!'',
+    floatWidth: 500,
+    forceCustomRendering: false,
+    nativeOnDevice: ['Android', 'BlackBerry', 'iPhone', 'iPad', 'iPod', 'Opera Mini', 'IEMobile', 'Silk'],
+    outputAsCSV : false,
+    csvSepChar : ',', 
+    okCancelInMulti: true, 
+    isClickAwayOk: false,
+    triggerChangeCombined : true,
+    selectAll : false,
+    selectAllPartialCheck : true,
+    search : false,
+    searchText : 'Search...',
+    searchFn : function(haystack, needle, el){ ... },
+    noMatch : 'No matches for "{0}"',
+    prefix : '',
+    locale :  ['OK', 'Cancel', 'Select All'],
+    up : 'false',
+    showTitle : 'true',
+    max : null,
+    renderLi : (li, originalOption) => li,
+}
+
+
+ +

Events

+

Sumoselect raise some very helpful events on which you can hook your custom handlers.

+ + 
+$('select.SlectBox').on('sumo:opened', function(sumo) {
+    // Do stuff here
+    console.log("Drop down opened", sumo)
+});
+
+

+ Available events +

+ 
+// Drop down initialized.
+sumo:initialized
+// Drop down opening
+sumo:opening
+// Drop down opened
+sumo:opened
+// Drop down closing
+sumo:closing
+// Drop down closed.
+sumo:closed
+// Drop down unloaded.
+sumo:unloaded
+
+

Methods

+ +

To call below functions you need to get the instance of SumoSelect object which can be done as + +

+ 
 var MySelect;
+$(document).ready(function () {
+            MySelect = $('.SlectBox').SumoSelect();
+     });
+
+
+ +

Or simply you can get the instance from select element directly i.e. + +

+ 
 var MySelect = $('select.SlectBox')[0].sumo;
+
+ +

Note : The SumoSelect object is directly binded with native select element not with the jquery object of + element. + +

Following is the list of methods of SumoSelect. +

    +
  • + .unload() + +

    Deactivate the SumoSelect plugin and display original select element. ( You can reinitialize the SumoSelect + for this select. ) + +

    + 
     $('select.SlectBox')[0].sumo.unload();
    +
    + +
    • +
  • + .add(value [,text][,index][,attrs]) + +

    Insert an new item in the select at a given index if index is provided else added to last. use index 0 to + insert at the begining. + +

    + 
    // adds a option with value and html set to 'india' at the last.
+$('select.SlectBox')[0].sumo.add('india');
+
+// adds a option with value and html set to 'india' at index no 3.
+$('select.SlectBox')[0].sumo.add('india',3);
+
+// adds a option with value = 'india' and html = 'Indian' at the last.
+$('select.SlectBox')[0].sumo.add('india','Indian');
+
+// adds a option with value and html set to 'india' at index no 0.
+$('select.SlectBox')[0].sumo.add('india','Indian',0);
    +// adds a option with value and html set to 'india' at index no 0 with some attributes. +$('select.SlectBox')[0].sumo.add('india','Indian',0, {'data-test': 'test'}); +
    + +
    • +
  • + .remove(index) + +

    Removes an item from a given index number. + +

    + 
     $('select.SlectBox')[0].sumo.remove(2);
    +
    + +
    • +
  • + .selectItem(index/value) + +

    Selects (check an item) an item in the list by index or by its value. You can select multiple items in case of a multiselect. + +

    + 
    //selects the item at index 2
+ $('select.SlectBox')[0].sumo.selectItem(2);
+ //selects the item having value "volo"
+ $('select.SlectBox')[0].sumo.selectItem('volo');
    +
    + +
    • +
  • + .unSelectItem(index/value) + +

    unselect (uncheck an item) an item in list by index or by value + +

    + 
    //unselects the item at index 2
+ $('select.SlectBox')[0].sumo.unSelectItem(2);
+ //unselects the item having value "volvo"
+ $('select.SlectBox')[0].sumo.unSelectItem('volvo');
    +
    + +
    • +
  • + .disableItem(index) + +

    Disables and item in the list + +

    + 
    //disables the item at index 2
+ $('select.SlectBox')[0].sumo.disableItem(2);
    +
    + +
    • +
  • + .enableItem(index) + +

    Enables and item in the list + +

    + 
    //enables the item at index 2
+ $('select.SlectBox')[0].sumo.enableItem(2);
    +
    + +
    • +
  • + .selectAll() + +

    Selects all items list + +

    + 
    //selects all items (excluding disabled)
+ $('select.SlectBox')[0].sumo.selectAll();
    +
    + +
    • +
  • + .unSelectAll() + +

    Un selects all items in the list + +

    + 
    //Un select all items
+ $('select.SlectBox')[0].sumo.unSelectAll();
    +
    + +
    • +
  • + .enable() +

    Enables the SumoSelect control +

    + 
    $('select.SlectBox')[0].sumo.enable();
    +
    +
    • +
  • + .disable() +

    Disable the SumoSelect control +

    + 
    $('select.SlectBox')[0].sumo.disable();
    +
    +
    • +
  • + .unSelectAll() +

    Un selects all items in the list +

    + 
    //Un select all items
+$('select.SlectBox')[0].sumo.unSelectAll();
    +
    +
    • +
  • + .reload() +

    This method reloads the UI over original select element. so now you can perform the desired operations on underlying select element and then update the UI od sumoselct after that. +

    + 
    //Reloads the UI of plugin.
+$('select.SlectBox')[0].sumo.reload();
    +
    +
    • + + +
+ +

*** You can add custom css class to options (css class added to option is added to the generated li.) + +

+ License

+ +

Copyright (c) 2014 Hemant Negi Licensed under the MIT license. +

+ + +
+
+ + + + diff --git a/jquery.sumoselect.js b/jquery.sumoselect.js index 102b580..4325fb7 100644 --- a/jquery.sumoselect.js +++ b/jquery.sumoselect.js @@ -26,13 +26,13 @@ // Extra check for IE compatibility const dispatchEvent = (target, eventName) => { let event = null; - if(typeof(Event) === 'function') { - event = new Event(eventName, { - bubbles: true - }); - }else{ - event = document.createEvent('Event'); - event.initEvent(eventName, true, true); + if (typeof (Event) === 'function') { + event = new Event(eventName, { + bubbles: true + }); + } else { + event = document.createEvent('Event'); + event.initEvent(eventName, true, true); } target.dispatchEvent(event); @@ -58,10 +58,10 @@ isClickAwayOk: false, // for okCancelInMulti=true. sets whether click outside will trigger Ok or Cancel (default is cancel). triggerChangeCombined: true, // im multi select mode whether to trigger change event on individual selection or combined selection. selectAll: false, // to display select all button in multiselect mode.|| also select all will not be available on mobile devices. - + selectAllPartialCheck: true, // Display a disabled checkbox in multiselect mode when all the items are not selected. search: false, // to display input for filtering content. selectAlltext will be input text placeholder searchText: 'Search...', // placeholder for search input - searchFn (haystack, needle) { // search function + searchFn(haystack, needle) { // search function return haystack.toLowerCase().indexOf(needle.toLowerCase()) < 0; }, noMatch: 'No matches for "{0}"', @@ -97,7 +97,7 @@ lastUnselected: null, selectedCount: 0, - createElems () { + createElems() { const O = this; const selectedOptions = O.E.find('option:checked'); O.E.wrap('