+ The Slider widget is a UI control that enables the user to adjust + values in a finite range along a horizontal or vertical axis. + Typically, the Slider widget is used in a web application as a visual + replacement for an input box that takes a number as input. +
+Getting Started
+ ++To include the source files for Slider and its dependencies, first load +the YUI seed file if you haven't already loaded it. +
+ +<script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script>+ + +
+Next, create a new YUI instance for your application and populate it with the
+modules you need by specifying them as arguments to the YUI().use() method.
+YUI will automatically load any dependencies required by the modules you
+specify.
+
<script>
+// Create a new YUI instance and populate it with the required modules.
+YUI().use('slider', function (Y) {
+ // Slider is available and ready for use. Add implementation
+ // code here.
+});
+</script>
+
+
+
+For more information on creating YUI instances and on the
+use() method, see the
+documentation for the YUI Global Object.
+
Using Sliders
+ +Anatomy of a Slider
+ +DOM structure
+ +
+ A Slider is comprised of a thumb that slides along a rail. In the DOM, the
+ thumb is a child of the rail element. The visualization of the rail is
+ created by applying a CSS background image to the rail element and two
+ child elements used to display the rail's end caps. The thumb contains two
+ <img> elements, one for the thumb graphic and one for
+ its shadow. Using an <img> in the DOM rather than a
+ background image for the thumb circumvents a performance issue in older
+ versions of Internet Explorer.
+
+ The rail element is contained within the standard contentBox
+ and boundingBox common to all YUI 3 Widgets.
+
+ Like other form controls, Sliders are inline elements. +
+ ++ The complete markup of a Slider is as follows: +
+ +
+Note: be sure to add the yui3-skin-sam classname to the
+page's <body> element or to a parent element of the widget in order to apply
+the default CSS skin. See Understanding Skinning.
+
<body class="yui3-skin-sam"> <!-- You need this skin class -->+ + +
<!-- boundingBox --> +<span class="yui3-widget yui3-sliderbase yui-slider"> + <!-- contentBox --> + <span class="yui3-slider-content yui3-slider-x"><!-- or slider-y --> + + <!-- rail --> + <span class="yui3-slider-rail"> + <span class="yui3-slider-rail-cap-left"></span><!-- or cap-top --> + <span class="yui3-slider-rail-cap-right"></span><!-- or cap-bottom --> + + <!-- thumb --> + <span class="yui3-slider-thumb"> + <img class="yui3-slider-thumb-shadow"> + <img class="yui3-slider-thumb-image"> + </span> + </span> + + </span> +</span>+ + +
Appearance
+ ++ This is the appearance of a Slider with default Sam skin applied: +
+ +
+
+
+
++ See the skinning section below for tips on creating + your own skin or using one of the prepackaged skins available for Slider as + of version 3.1. +
+ +Thumb and end cap placement
+ +
+ The Slider thumb is positioned within the dimensional boundaries of the
+ rail element. The skin CSS positions the rail's end caps just outside the
+ rail. The rail element's height or width, for vertical or horizontal
+ Sliders respectively, is configured by the length attribute.
+ The default length is 150px. Due to the end caps, the actual
+ footprint of the Slider is a few pixels longer than the
+ length.
+
+
+Instantiating and configuring a Slider
+ ++ There is no required configuration to instantiate a Slider. By default, + Sliders are horizontal, 150px wide, and report values from 0 to 100. Below + are the configuration attributes available for Slider (excluding those + inherited from Widget): +
+ +| Attribute | +Description | +Default | +
|---|---|---|
axis |
+ Specifies horizontal or vertical Slider ("y" for vertical) | +"x" | +
min |
+ Value at the far left or top of the rail | +0 | +
max |
+ Value at the far right or bottom of the rail | +100 | +
value |
+ The initial value, which will be translated into initial thumb placement | +0 | +
length |
+ Height of vertical Slider rail; width of horizontal Slider rail | +150px | +
thumbUrl |
+ The path to an image to use as the <img> for the thumb |
+ Appropriate thumb image for the configured axis in the current skin | +
clickableRail |
+ Clicking on the rail moves the thumb to that point | +true | +
+ Here are a few ways to instantiate a Slider: +
+ +YUI({...}).use('slider',function (Y) {
+
+ // Default everything
+ var slider = new Y.Slider();
+ slider.render("#slider-parent");
+
+ // Use a custom thumb and width
+ var slider = new Y.Slider({
+ length : '200px',
+ thumbUrl : '/path/to/local/thumb-image.png'
+ });
+ slider.render('#slider-parent');
+
+ // Vertical slider with values that increase from bottom to top and
+ // initialize the thumb in the middle.
+ var slider = new Y.Slider({
+ axis : 'y',
+ min : 100,
+ max : 0,
+ value : 50
+ });
+ slider.render('#slider-parent');
+});
+
+
+Setting and constraining the Slider value
+ +Setting and getting Slider values
+ +
+ Like any input element, the most important thing about a Slider is its
+ value. Though value is managed as an attribute,
+ Slider provides two convenience methods for accessing it:
+
-
+
getValue()
+ setValue(newVal)
+
// Specify value at construction
+var slider = new Y.Slider({
+ value : 50
+});
+
+// Get and set the value as an attribute
+var val = slider.get('value');
+
+slider.set('value',val + 10);
+
+// Use the Slider API convenience methods
+val = slider.getValue();
+
+slider.setValue(val - 20);
+
+
+
+Constraining Slider values
+ +
+ A Slider's value is constrained between the configured
+ min and max attribute values. Values outside
+ this range are treated as the closer of min or
+ max.
+
// Create a horizontal Slider 300px wide with values from -100 to 100
+var slider = new Y.Slider({
+ length : 300,
+ min : -100,
+ max : 100
+});
+
+slider.setValue(-200); // same as setValue(-100)
+
+
+
+ By default, min is 0, max is
+ 100 and value is 0.
+
min and max for vertical Sliders
+
+
+ Vertical Sliders associate the top edge of the rail with the
+ min value and the bottom edge of the rail with the
+ max. If you prefer values to increase from bottom to top,
+ just flip the specified min and max values.
+
// Create a vertical Slider with value 0 at the bottom, 100 at the top
+var v_slider = new Y.Slider({
+ axis : 'y',
+ min : 100, // vertical Sliders have min at the top
+ max : 0,
+ value : 33 // initial value
+});
+
+
+Sync the UI if the Slider was rendered off the DOM
+ +
+ If a Slider is rendered off the DOM, you must call the Slider's
+ syncUI() method after attaching it to the DOM in order for the
+ thumb to be placed correctly. When off DOM, the dimensional information
+ necessary to place the thumb is unavailable.
+
// Create a Slider and render it to an element not on the DOM
+var container = Y.Node.create("<div></div>");
+
+var slider = new Y.Slider({ value: 30 });
+
+slider.render( container );
+
+...
+
+// Insert the Slider's container into the DOM
+Y.one( "body" ).insert( container );
+
+// Call syncUI() to sync the thumb to the current value
+slider.syncUI();
+
+
+Slider events
+ ++ Sliders fire the following events during operation: +
+ +| Event | +When | +Payload | +
|---|---|---|
slideStart |
+ Beginning a thumb drag | +{ ddEvent: (drag:start event) } |
+
thumbMove |
+ The thumb position is being changed | +{ ddEvent : (drag:drag event) } |
+
valueChange |
+ The value attribute is changed by any means | +Normal change event signature (newVal, prevVal, etc). When dragging, extra event property ddEvent : (drag:drag event) is added |
+
slideEnd |
+ Finishing a thumb drag | +{ ddEvent: (drag:end event) } |
+
railMouseDown |
+ The rail was clicked | +{ ev: (DOM mousedown event) } |
+
+ This is not an exhaustive list. See the API docs for a complete listing. +
+ +Skinning
+ +
+Note: be sure to add the yui3-skin-sam classname to the
+page's <body> element or to a parent element of the widget in order to apply
+the default CSS skin. See Understanding Skinning.
+
<body class="yui3-skin-sam"> <!-- You need this skin class -->+ + +
Using custom thumb or rail images
+ ++ You can use alternate rail images by specifying a new image path in your + CSS, and alternate thumbs can be targeted in the Slider configuration. +
+ +<style type="text/css">
+/* The rail and end cap images are shared in a sprite.
+ * Include the id of the slider container to increase css specificity */
+.yui3-skin-sam #slider-parent .yui3-slider-x .yui3-slider-rail,
+.yui3-skin-sam #slider-parent .yui3-slider-x .yui3-slider-rail-cap-left,
+.yui3-skin-sam #slider-parent .yui3-slider-x .yui3-slider-rail-cap-right {
+ background-image: url(/path/to/new/rail.png);
+}
+</style>
+
+<script>
+YUI().use( "slider", function (Y) {
+
+ var slider = new Y.Slider({
+ thumbUrl: '/path/to/new/thumb.png'
+ });
+
+ slider.render("#slider-parent");
+
+});
+</script>
+
+
+Available skins
+ ++ Slider is provided with several alternate skins that can be applied by + configuring a skin override in your YUI instance configuration. +
+ +YUI({
+ skin: {
+ overrides: {
+ slider: [ 'round-dark' ]
+ }
+ }
+}).use( "slider", ... );
+
+
++ The available skins are each provided in a light and dark theme. A few + include optional thumbs or rails (for both light and dark). +
+ +| Skin class | +Visualization | +Optional | +
|---|---|---|
yui3-skin-sam |
+  |
+ + |
 |
+
+ rail-x-lines.png
+ |
+ |
yui3-skin-sam-dark |
+  |
+ + |
yui3-skin-capsule |
+  |
+ + |
 |
+
+ thumb-x-line.png
+ |
+ |
 |
+
+ rail-x-dots.png
+ |
+ |
 |
+
+ rail-x-lines.png
+ |
+ |
yui3-skin-capsule-dark |
+  |
+ + |
yui3-skin-round |
+  |
+ + |
 |
+
+ thumb-x-grip.png
+ |
+ |
yui3-skin-audio-light |
+  |
+ + |
yui3-skin-audio |
+  |
+ + |
+ Here's an example illustrating using the capsule skin with provided + alternate rail and thumb: +
+ +<style type="text/css">
+// The rail and end cap images are shared in a sprite
+.yui3-skin-capsule .yui3-slider-x .yui3-slider-rail,
+.yui3-skin-capsule .yui3-slider-x .yui3-slider-rail-cap-left,
+.yui3-skin-capsule .yui3-slider-x .yui3-slider-rail-cap-right {
+ background-image: url(/path/to/build/slider-base/assets/skins/capsule/rail-x-lines.png);
+}
+</style>
+
+<script>
+YUI({ skin: { overrides: { slider: [ 'capsule' ] } } })
+ .use( "slider", function (Y) {
+
+ var slider = new Y.Slider({
+ axis : 'y',
+ min : 1,
+ max : 5,
+ value : 3,
+ length : '100px',
+ thumbUrl: Y.config.base + '/slider-base/assets/skins/capsule/thumb-x-line.png'
+ });
+
+ slider.render("#slider-parent");
+
+});
+</script>
+
+
+Skin image sprites
+ ++ To reduce the number of resource requests for Slider's visual treatment, + the rail and end caps are combined into one image sprite, and thumb and + shadow into another (examples shown below with borders added for + clarity). +
+ + + +
+
+
+ Thumb and shadow sprite. As noted above, the thumb
+ and shadow are both represented as <img>s in the DOM.
+ This sprite allows both <img>s to reference the same
+ src URL, but masked and positioned appropriately by the skin
+ CSS. Thumb image and shadow for vertical Sliders are set next to each
+ other horizontally as shown. Horizontal Slider thumb sprites are stacked
+ vertically.
+
+
+
+ Rail image (repeated across length), top cap, and bottom cap
+ sprite. This sprite is assigned in the skin CSS as the
+ background-image for the rail element and the two end caps.
+ The CSS background for the rail is set to repeat vertically or
+ horizontally, relative to the Slider axis. The image need be
+ only as tall (vertical) or wide (horizontal) as the end caps unless the
+ rail includes a more involved repeating section, such as the audio skin.
+ End caps should be aligned against the top edge for vertical rails, or the
+ left edge for horizontal rails.
+
+ Standard heights and widths are used for the placement of the image bits + within the sprites to allow for minimal differences between the CSS in one + skin versus another. This allows you to start from an existing skin and + change very little of the CSS (potentially only swapping image URLs) to + achieve a new look and feel. +
+ +Extending Slider
+ +
+ Slider is built up from a base implementation (Y.SliderBase)
+ that has no notion of value. It is just a draggable thumb on a rail. The
+ slider-value-range submodule provides an extension class that
+ adds the attributes, API, and logic relating the thumb's position to a
+ value within a minimum and maximum
+ range. Similarly, the clickableRail implementation is
+ relegated to an extension class. These classes are combined with
+ Y.Base.build to generate the Y.Slider class.
+
+ If you want to use a different value algorithm or decorate the basic Slider
+ in other ways, you can write an extension class or Y.extend an
+ existing extension class and create a new Slider implementation with
+ Y.Base.build.
+
YUI().use( "slider-base", function (Y) {
+
+ // Define a new extension class to calculate values differently
+ function MyValueClass() {
+ this._initValueAlgo();
+ }
+
+ // Add attribute configuration and prototype to decorate the Slider
+ Y.mix( MyValueClass, {
+
+ ATTRS: { /* new configuration attributes */ },
+
+ prototype: { /* additional prototype members and methods */ }
+ });
+
+
+ // Combine SliderBase with the new extension class any others to
+ // create a new Slider
+ Y.MySlider = Y.Base.build( "slider", Y.SliderBase, [
+ Y.ClickableRail, // Should also support rail clicks
+ MyValueClass // Use the new value methods and attributes
+ ] );
+
+
+ // Instantiate and use the new Slider class as you would Y.Slider
+ var slider = new Y.MySlider({ /* config */ });
+
+ slider.render( "#slider-parent" );
+
+});
+
+