selectybox
v1.4.0
Published
Allows simple styling of <select> boxes in a way that is both accessible and mobile friendly.
Downloads
74
Readme
Selectybox
... simple wrapper to allow fancy styling of <select>
boxes while being both both accessible and mobile friendly.
0: Install and inclusion
npm install selectybox
SelectyBox is CommonJS (require()
) friendly, using module.exports
by default -- setting Selectybox
as a global object only as last resort.
Selectybox comes with a nifty jQuery/Zepto plugin factory (See below).
1. Basic Usage
var Selectybox = require('selectybox');
...or if you loaded the script with a <script>
tag:
var Selectybox = window.Selectybox;
Running the conctructor creates the necessary elements and event handlers and returns a Selectybox widget instance.
var selectElm = document.getElementsByTagName('select')[0];
var widget = Selectybox( selectElm , options ); // using `new` is optional
2. Options
Selectybox accepts the following options (showing default values):
var options = {
templ: '<span class="selecty"><span class="selecty-button"/></span>',
getButton: function () { return this.container.firstChild; },
focusClass: 'focused',
disabledClass: 'disabled',
emptyClass: 'emptyvalue',
emptyVal: '\u00a0 \u00a0 \u00a0',
text: function (txt) { return txt; }, // <-- it's OK to add HTML markup
selectCSS: {
// set necessary styles
position: 'absolute',
bottom: 0,
left: 0,
width: '100%',
height: '100%',
// unset existing styles
top: 'auto',
right: 'auto',
margin: 0,
padding: 0,
border: 0
},
};
- templ - is the HTML describing the
widget.container
element. The template also contains thewidget.button
element (holding the displayed text value). - getButton - describes where the
widget.button
is within thewidget.container
template. - focusClass -- additional class-name for the
widget.container
while the<select>
is focused. - disabledClass -- additional class-name for the
widget.container
while the<select>
is disabled. - emptyClass -- additional class-name for the
widget.container
when the<select>
's value is""
. - emptyVal -- String to display instead of an empty string inside
widget.button
- text -- function that allows dynamic modification of the displayed text.
- selectCSS -- CSS properties to apply to the
<select>
while the widget is active.
NOTE: The option defaults can be changed via Selectybox.prototype.*
3. Widget references
The widget object contains references to its key elements:
widget.select; // the original <select> element
widget.button; // proxy element that contains the display text
widget.container; // wrapper around both `widget.select` and `widget.button`
...and a reverse-lookup for <select>
's widget is also possible:
Selectybox.getWidget( selectElm ) === widget; // true
4. Methods
If the <select>
's value, or disabled state has been updated (and no change
event triggered), then you can silently refresh the widget by running:
widget.refresh();
To silently update the <select>
's value (and refresh
the widget's display text) without triggering a DOM change event run:
widget.val( 'Apple' );
To change the <select>
's disabled
property, and set the widget's disabledClass accordingly:
widget.disable(); // disable
widget.disable( false ); // enable
To remove the injected elements, inline styling an event handlers, simply do
widget.destroy();
You can run Selectybox()
again for the same <select>
(e.g. with new options) returns the existing widget, but with the new options applied and new container
and button
elements in place. (This uses the destroy
method internally.)
Selectybox( selectElm, newOptions ) === widget; // true
jQuery/Zepto Plugin Factory
Selectybox comes with a small jQuery plugin factory Class method called Selectybox.jQueryPlugin()
.
If window.jQuery
is detected, the following command is automatically run:
Selectybox.jQueryPlugin( window.jQuery );
(The factory can be run manually against one or more instances of jQuery/Zepto)
...
Invoking the plugin is easy, and its options are fed straight into the Selectybox constructor:
var $mySelect = $('select:first');
var widgetContainer = $mySelect.selectybox( options );
The plugin provides jQuery UI like access to the widget methods:
$mySelect.selectybox('refresh'); // .refresh()
$mySelect.selectybox('val', 'Apple'); // .val('Apple')
$mySelect.selectybox('disable', false); // .val(false)
$mySelect.selectybox('destroy'); // .destroy()
Access to the raw widget
is provided so:
var widget = $mySelect.selectybox('widget');