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