https://github.com/slantz/selectum
Custom native HTML5 select, using data attributes and vanilla JS events which can update url search params via history API and show subsets of other custom selects.
https://github.com/slantz/selectum
Last synced: 4 months ago
JSON representation
Custom native HTML5 select, using data attributes and vanilla JS events which can update url search params via history API and show subsets of other custom selects.
- Host: GitHub
- URL: https://github.com/slantz/selectum
- Owner: slantz
- License: mit
- Created: 2016-02-01T19:02:04.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2016-02-23T17:21:08.000Z (over 10 years ago)
- Last Synced: 2025-12-25T17:06:54.903Z (6 months ago)
- Language: JavaScript
- Size: 69.3 KB
- Stars: 11
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Selectum
[](https://www.npmjs.com/package/selectum)
[](http://bower.io/search/?q=selectum)
[](https://www.npmjs.com/package/selectum)
> Custom native HTML5 select, using data attributes and vanilla JS events which can update url search params via history API and show subsets of other custom selects. Can have reset button to pick any value or reset dependent selects. Has an ability to set default palceholder text. Click can be handled via plugin or set with special data attribute.
> Great for Server or Client side rendering!!!
> This is fully jQuery or other libraries independent plugin, can be fully configured with ```[data-attributes]``` or via JS constructor function.
> It's always annoying and irretating when minified labrary renders it's markup and you have to debug it, if your HTML structure totally differs. One of the main advantages of this plugin is that it doesn't render any precompiled layout, you can attach this plugin to any HTML structure and configure it via data attributes or proper css classes. It acts as a separate module or web component.
### [Demo](https://slantz.github.io/selectum/)
##### It uses:
1. classList API
2. History API tomanipualte URL
3. polyfill for ```Element.prototype.closest```
4. initEvent (initCustomEvent for IE)
5. css classes for down and up arrows
6. on/off callbacks
7. location.search to selelct initial values
##### Settings:
- Attributes:
- [data-selectum]
- [data-selectum-render]
- [data-selectum-exist]
- [data-selectum-head]
- [data-selectum-hiddable]
- [data-selectum-clickable]
- [data-selectum-current]
- [data-selectum-reset]
- [data-selectum-list]
- [data-selectum-id]
- [data-selectum-val]
- [data-selectum-picker]
- [data-selectum-picked]
- [data-selectum-emit]
- [data-selectum-emit-reset]
- [data-selectum-listen]
- [data-selectum-listen-reset]
- [data-selectum-placeholder]
- [data-selectum-update-url]
- [data-selectum-url-fetch]
- [data-selectum-temp-head] \(for custom templates to attach styles to 'Loading...' label\)
- JS:
```javascript
new Selectum(el, {
picker: true,
picked: false,
render: false,
exist: false,
title: 'Vegetables Selector',
emit: 'selectCode',
emitReset: 'resetAll',
listen: 'seelctNumber',
listenReset: 'resetCode',
defaultText: 'Set code',
updateUrl: true,
urlFetch: true,
hiddable: 'fruit'
});
```
##### Methods:
- on
- off
- render
##### Events:
- before:select
- select
- reset
- reset:picked
- before:open
- open
- init:url
- url:update
###### Usage:
```javascript
var select = new Selectum(document.querySelector('[data-selectum]'));
select.on('before:select', function(oldVal){
// triggered when before some option would be selected
});
select.on('select', function(selectedVal){
// triggered when some option was selected
});
select.on('reset', function(selectedVal){
// triggered when reset button was clicked
});
select.on('reset:picked', function(selectedVal){
// triggered when select was reset by the picker one
});
select.on('before:open', function(selectedVal){
// triggered when select was clicked and not opened yet
});
select.on('open', function(selectedVal){
// triggered when select was opened after click
});
select.on('init:url', function(selectedVal){
// triggered when value was set from URL on initiation
});
select.on('url:update', function(selectedVal){
// triggered if select should update url and after URL was updated with selected value
});
select.off('click');
```
> IE10+
### Simple HTML5 Dropdown:
> This is single select which updates history pushState, configured via data-attributes and has no dependent selects.
```html
Color Picker
- Any
- red
- yellow
- green
- blue
```
### Url updating select:
> In despite of the previous one this select can update url using History API and *can be updated* from URL parameter with the *lang* name. E.g. after selecting English as a language the URL will become smth like `location.origin/?lang=en`. The page won't be reloaded as pushState method is invoked.'
```html
- Default (EN)
- English
- Deutsch
- Francaise
- Русский
```
### Main Select and Dependent one:
> This is single select which updates history pushState, configured via data-attributes and has no dependent selects.
##### Differences:
1. has ```[data-selectum-picker]``` attribute, which generates proper css ```#selectum-hiding-styles``` that filter dependent selects subsets;
2. has ```[data-selectum-emit]``` attribute, here it emites *countryPicked* event and plugin with ```[data-selectum-listen="countryPicked"]``` will listen for this event to enable oneself and clean url parameter if necessary;
3. doesn't have ```[data-selectum-clickable]``` so open event will be triggered on ```[data-selectum]``` element click, i.e. plugin.
```html
Eurasia
- Any
- United Kingdom
- Germany
- France
- Ukraine
Eurasia
Any
- London
- Bakewell
- Berlin
- Aachen
- Paris
- Marseille
- Odessa
- Kiev
```
### Main Select and Dependent one reset:
> This plugin in despite of the previous one after reset button is clicked will set the dependent one to it's raw state, using ```js-raw``` class.
```html
Eurasia
- Any
- United Kingdom
- Germany
- France
- Ukraine
Eurasia
Any
- London
- Bakewell
- Berlin
- Aachen
- Paris
- Marseille
- Odessa
- Kiev
```
### Select rendered by client with a default template:
> This select can be rendered dynamically by client side and configured either by attribtes or js means.
Custom array of objects or string of elements should be passed to select
```javascript
var select = null;
[].slice.call( document.querySelectorAll('[data-selectum]') ).forEach( function(el) {
select = new Selectum(el);
});
window.setTimeout(function() {
select.render({
head: select.options.head || 'Any other head', // Optional
items: [
{id : 0, val : 'apple'},
{id : 1, val : 'banana'},
{id : 2, val : 'tangerin'}
]
})
}, Math.random() * 2000 + 1000);
```
```html
```
> This will be rendered into
```html
Buy a Fruit
Get your Fruit
- Any
- apple
- banana
- tangerin
```
### Select rendered by client with a default template:
> This is the dependent select which depend on the fruit one, that can be set via ```[data-selectum-hiddable="fruit"]``` attribute or with js by passing ```listen: 'fruit'``` setting key.
Custom array of objects or string of elements should be passed to select
```javascript
var select = null;
[].slice.call( document.querySelectorAll('[data-selectum]') ).forEach( function(el) {
select = new Selectum(el);
});
window.setTimeout(function() {
select.render({
head: select.options.head || 'Any other head', // Optional
listen: 'fruit', // Optional, just for example, unnecessary here as it's duplicated via data-selectum-hiddable attribute
items: [
{
id : '0',
val : [
{id : 00, val : 'green'},
{id : 01, val : 'red'},
{id : 02, val : 'yellow'}
]
},
{
id : '1',
val : [
{id : 10, val : 'fresh'},
{id : 11, val : 'rotten'},
{id : 12, val : 'green'}
]
},
{
id : '2',
val : [
{id : 20, val : 'sweet'},
{id : 21, val : 'sour'},
{id : 22, val : 'mild'}
]
}
]
})
}, Math.random() * 2000 + 1000);
```
```html
```
> This will be rendered into
```html
Fruit Type
Get your Fruit
Any
- green
- red
- yellow
- fresh
- rotten
- green
- sweet
- sour
- mild
```
### Select rendered by client with a custom template:
> This select can be rendered dynamically by client side and configured either by attribtes or js means.
Custom array of objects or string of elements should be passed to select
```javascript
var select = null;
[].slice.call( document.querySelectorAll('[data-selectum]') ).forEach( function(el) {
select = new Selectum(el);
});
window.setTimeout(function() {
select.render({
items: [
{id : 0, val : 'apple'},
{id : 1, val : 'banana'},
{id : 2, val : 'tangerin'}
]
})
}, 3000);
window.setTimeout(function() {
select.render({
head: 'Totally changed head',
items: [
{id : 0, val : 'some'},
{id : 1, val : 'other'},
{id : 2, val : 'array'},
{id : 3, val : 'maybe'},
{id : 4, val : 'enormous'}
]
})
}, 7000);
```
```html
<%=head%>
- Any
<% for ( var i = 0; i < items.length; i++ ) { %>
- <%=items[i].val%>
<% } %>
```
> This will be rendered straight into this first
```html
Totally changd head
Get your Fruit
- Any
- some
- other
- array
- maybe
- enormous
```