Mobile-first HTML5 slider component. Demo at http://slider.zhenya.co
Include:
slider.js
orslider.min.js
slider.css
orslider.min.css
To instantiate a slider, pass a root element and an optional config object to the constructor. If a selector is passed in that matches more than one element, the first element will be used.
var myslider = new Slider("#slider", {
min: 0,
max: 1
});
Use the template helper {{>slider}}
to instantiate a slider. The data context of the slider will be assumed to be the options object if and only if there are some keys on that object that are also present on Slider.defaults
. In other words, if the data context looks like a slider options object, it will be used.
This makes it easy to pass options to the slider directly from the template:
{{>slider min=0 max=100 step=1 value=foobar}}
Reactive value binding
In the example above, if there is a key on the data context called foobar
that returns a numeric value, it will reactively control the value of the slider.
Slider.defaults =
min: 0 # minimum value
max: 1 # maximum value
value: 0 # initial value
step: 0.1 # minimum step size
warnings: true # log warnings to the console
orientation: 'horizontal' # can be 'vertical' or 'horizontal'
transitionDuration: 350 # animation duration, must be same as in CSS
poll: false # automatically refresh all sliders periodically
formElement: null # connect slider value to a form element via a selector
knob:
dragEvents: true # fire drag events
label:
location: 'knob' # location of label
precision: 1 # how many decimal places
popup: true # does label pop up when dragged
format: (v, options) -> Slider._.formatNumber v, decimalPlaces: options.precision
# how to format the numeric value to a string
Call this function with no arguments (or an undefined first argument) to retrieve the current normalized position.
Pass a numeric argument in the range 0..1
to set the slider to a normalized position. Pass a second argument to configure specific behaviour of the call. Default values:
normalized: true # if the first argument is in the range 0..1 or options.min..options.max
transition: @options.transitionDuration # pass a falsey value to disable smooth transitions
changeEvent: true # whether or not to fire the change event
transitionEvent: true # whether or not to fire the transitioned event after the transition
step: if options?.normalized is false then @options.step else @options.step / (@options.max - @options.min)
# override step size (this is set to false during dragging for example)
updateFormElement: true # whether or not to update form value after the set
Call with no arguments to retrieve the current value in the range options.min..options.max
Pass a value in the range options.min .. options.max
to set the slider to a specific value. Options are the same as in position()
. Equivalent to slider.position(value, {normalized: false});
Slider throws three kinds of events on the main DOM element slider.element
. These are change
, drag
, and transition
. When handling the change
event, the current slider value is accessible through the event's value
property. If receiving a jQuery wrapped event, event.originalEvent.value
.
change
is fired immediately when the position changes, before any transitions begindrag
is fired whenever the user moves the knob,event.value
andevent.position
are availabletransition
is fired when the knob is finished transitioning after the knob is released or an animation finishes after callingslider.position(p)
orslider.value(v)
The slider instantiates child components based on the configuration in Slider.components
. The core pieces of slider: the knob, track, and label are also components.
Slider.components =
track: -> Track
knob: -> Knob
label: -> Label
fill: (o) -> Fill if o.fill?
debug: (o) -> Debug if o.debug
Each value in this object is a function that takes an options object and is expected to return a compnent constructor. If one is returned, the component is instantiated and assigned under the same key to the slider instance. For example:
var slider = new Slider('#slider');
slider.track // is the slider's track instance
The signature of a component constructor is (slider, options)
where the options is borrowed from the main slider's options object under the key name of the component. This means you can pass options to components by using the same key as in the component definition.
To disable the knob popup for example:
slider = new Slider '#slider',
min: 0
max: 1
knob:
popup: false
Adding your own component is easy:
class Widget
constructor: (@slider, options) ->
Slider.components.widget = (o) -> Widget
myWidgetSlider = new Slider '#slider',
min: 0
max: 10
widget:
widgetOption: true
myWidgetSlider.widget # will return the widget component instance
or in JavaScript:
function Widget(slider, options) {
// construct away
}
Slider.components.widget = function(o) { return Widget; };
myWidgetSlider = new Slider(#slider, {
min: 0,
max: 1,
widget: {
widgetOption: true
}
});