slider.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
<entry name="slider" namespace="fn" type="widget" widgetnamespace="mobile" event-prefix="slide" init-selector="input[type='range'], :jqmData(type='range'), :jqmData(role='slider')">
	<title>Slider Widget</title>
	<desc>Creates a slider widget</desc>
	<longdesc>
		<h2>Slider</h2>

		<p>To add a slider widget to your page, use a standard input with the <code>type="range"</code> attribute. The input's value is used to configure the starting position of the handle and the value is populated in the text input. Specify <code>min</code> and <code>max</code> attribute values to set the slider's range. If you want to constrain input to specific increments, add the <code>step</code> attribute. Set the <code>value</code> attribute to define the initial value. The framework will parse these attributes to configure the slider widget.</p>
		<p>As you drag the slider's handle, the framework will update the native input's value (and vice-versa) so they are always in sync; this ensures that the value is submitted with the form.</p>
		<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>
		<p>The framework will find all <code>input</code> elements with a <code>type="range"</code> and automatically enhance them into a slider with an accompanying input without any need to apply a <code>data-role</code> attribute. To prevent the automatic enhancement of this input into a slider, add <code>data-role="none"</code> attribute to the input.</p>
		<p>In this example, the acceptable range is 0-100.</p>

<pre><code><![CDATA[
<label for="slider-1">Input slider:</label>
<input type="range" name="slider-1" id="slider-1" value="60" min="0" max="100">
]]></code></pre>

		<p>The default slider with these settings is displayed like this:
		<iframe src="/resources/slider/example1.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

		<ul>
			<li>
				<code>ui-slider</code>: The outermost container for slider.
				<ul>
					<li>
						<code>ui-slider-popup</code>: Tooltip popup element in case <code>data-popup-enabled</code> is <code>true</code>
					</li>
					<li>
						<code>ui-slider-input</code>: Input element of slider
					</li>
					<li>
						<code>ui-slider-track</code>: Slider's track
						<ul>
							<li>
								<code>ui-slider-handle</code>: Handle of slider's track
							</li>
						</ul>
					</li>
				</ul>
			</li>
		</ul>


		<h3>Step increment</h3>
		<p>To force the slider to snap to a specific increment, add the <code>step</code> attribute to the input. By default, the step is 1, but in this example, the step is 10 and the maximum value is 500.</p>
		<p>In this example, the acceptable range is 0-100.</p>

<pre><code><![CDATA[
<label for="slider-1">Input slider:</label>
<input type="range" name="slider-1" id="slider-1" value="60" min="0" max="100" step="10">
]]></code></pre>

		<p>This will produce an input that snaps to increments of 50. If a value is added to the input that isn't valid with the step increment, the value will be reset on blur to the closest step.
		<iframe src="/resources/slider/example2.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Fill highlight</h3>

		<p>To have a highlight fill on the track up to the slider handle position, add the <code>data-highlight="true"</code> attribute to the input. The fill uses active state swatch. </p>

<pre><code><![CDATA[
<label for="slider-fill">Input slider:</label>
<input type="range" name="slider-fill" id="slider-fill" value="60" min="0" max="100" data-highlight="true">
]]></code></pre>

		<iframe src="/resources/slider/example3.html" style="width:100%;height:90px;border:0px"></iframe>

		<h3>Mini version</h3>

		<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version. </p>

<pre><code><![CDATA[
<label for="slider-mini">Input slider:</label>
<input type="range" name="slider-mini" id="slider-mini" value="25" min="0" max="100" data-highlight="true" data-mini="true">
]]></code></pre>

		<p>This will produce a slider and its corresponding input that are not as tall as the standard version. The input also has a smaller text size.
		<iframe src="/resources/slider/example4.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Field containers</h3>

		<p>Optionally wrap the slider markup in a container with class <code>ui-field-contain</code> to help visually group it in a longer form. In this example, the step attribute is omitted to allow any whole number value to be selected.</p>
		<div class="warning">
			<p><strong>Note:</strong> The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</p>
		</div>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="slider-2">Input slider:</label>
	<input type="range" name="slider-2" id="slider-2" value="25" min="0" max="100">
</div>
]]></code></pre>

		<p>The slider is now displayed like this:
		<iframe src="/resources/slider/example5.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<p>Sliders also respond to key commands. Right Arrow, Up Arrow and Page Up keys increase the value; Left Arrow, Down Arrow and Page Down keys decrease it. To move the slider to its minimum or maximum value, use the Home or End key, respectively.</p>

		<h3>Calling the slider plugin</h3>

		<p>This plugin will auto initialize on any page that contains a text input with the <code>type="range"</code> attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:</p>

<pre><code><![CDATA[
$( "input" ).slider();
]]></code></pre>

		<h3>Theming the slider</h3>

		<p>To set the theme swatch for the slider, add a <code>data-theme</code> attribute to the <code>input</code> which will apply the theme to both the input, handle and track. The track swatch can be set separately by adding the <code>data-track-theme</code> attribute to apply the down state version of the selected button swatch.</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="slider-3">Input slider:</label>
	<input type="range" name="slider-3" id="slider-3" value="25" min="0" max="100" data-theme="b" data-track-theme="a">
</div>
]]></code></pre>

		<p>This will produce a themed slider:
		<iframe src="/resources/slider/example6.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h2>Flip Toggle Switch</h2>

		<div class="warning">
			<p><strong>Note:</strong> The flip toggle switch feature is deprecated as of jQuery Mobile 1.4.0. Use the <a href="../flipswitch/">Flipswitch widget</a> instead.</p>
		</div>

		<p>A binary "flip" switch is a common UI element on mobile devices that is used for binary on/off or true/false data input. You can either drag the flip handle like a slider or tap one side of the switch.</p>
		<p>To create a flip toggle, start with a <code>select</code> with two options. The first option will be styled as the "off" state switch and the second will be styled as the "on" state so write your options accordingly.</p>
		<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>

<pre><code><![CDATA[
<label for="flip-1">Flip switch:</label>
<select name="flip-1" id="flip-1" data-role="slider">
  <option value="off">Off</option>
  <option value="on">On</option>
</select>
]]></code></pre>

		<p>This will produce a basic flip toggle switch input. The default styles set the width of the switch to 100% of the parent container and stack the label on a separate line.
		<iframe src="/resources/switch/example1.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Longer Labels</h3>

		<p>The control is proportionally scaled, so to use longer labels one can just add a line of CSS setting the switch to the desired width. For example, given the following markup:</p>

<pre><code><![CDATA[
<div class="containing-element">
	<label for="flip-min">Flip switch:</label>
	<select name="flip-min" id="flip-min" data-role="slider">
		<option value="off">Switch Off</option>
		<option value="on">Switch On</option>
	</select>
</div>
]]></code></pre>

		<p><code>.containing-element .ui-slider-switch { width: 9em }</code> will produce:
		<iframe src="/resources/switch/example2.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<p>As some default styles hinge on fieldcontains, note that you may have to ensure that custom styles apply to switches within fieldcontains by using <code>.ui-field-contain div.ui-slider-switch { width: […]; }</code>.</p>

		<h3>Mini version</h3>

		<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version. </p>

<pre><code><![CDATA[
<label for="flip-mini">Flip switch:</label>
<select name="flip-mini" id="flip-mini" data-role="slider" data-mini="true">
	<option value="off">Off</option>
	<option value="on">On</option>
</select>
]]></code></pre>

		<p>This will produce a flip switch that is not as tall as the standard version and has a smaller text size.
		<iframe src="/resources/switch/example3.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Field containers</h3>

		<p>Optionally wrap the switch markup in a container with class <code>ui-field-contain</code> to help visually group it in a longer form. In this example, the step attribute is omitted to allow any whole number value to be selected.</p>
		<div class="warning">
			<p><strong>Note:</strong> The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</p>
		</div>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="flip-2">Flip switch:</label>
	<select name="flip-2" id="flip-2" data-role="slider" data-mini="true">
		<option value="off">Off</option>
		<option value="on">On</option>
	</select>
</div>
]]></code></pre>

		<p>The flip toggle switch is now displayed like this:
		<iframe src="/resources/switch/example4.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Theming the flip switch</h3>

		<p>Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the <code>data-theme</code> attribute on the <code>select</code> and specify a swatch letter.</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="flip-3">Flip switch:</label>
	<select name="flip-3" id="flip-3" data-role="slider" data-theme="b">
		<option value="no">No</option>
		<option value="yes">Yes</option>
	</select>
</div>
]]></code></pre>

		<p>This results in a switch with the swatch "b" colors for the handle. Note that the lefthand "on" state gets the active state color.
		<iframe src="/resources/switch/example5.html" style="width:100%;height:90px;border:0px"></iframe></p>
		<p>Here is a swatch "a" variation:
		<iframe src="/resources/switch/example6.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<p>It is also possible to theme the track of the flip switch by adding the <code>data-track-theme</code> attribute and specifying the chosen swatch letter on the <code>select</code>.</p>
		<p>Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="flip-5">Flip switch:</label>
	<select name="flip-5" id="flip-5" data-role="slider" data-theme="a" data-track-theme="b">
		<option value="no">No</option>
		<option value="yes">Yes</option>
	</select>
</div>
]]></code></pre>

		<iframe src="/resources/switch/example7.html" style="width:100%;height:90px;border:0px"></iframe>

		<h3>Calling the switch plugin</h3>

		<p>This plugin will auto initialize on any page that contains a text input with the <code>type="slider"</code> attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:</p>

<pre><code><![CDATA[
$( "input" ).slider();
]]></code></pre>

	<h3>Theming the flip switch</h3>

	<p>Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the <code>data-theme</code> attribute on the select and specify a swatch letter.</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="flip-3">Flip switch:</label>
	<select name="flip-3" id="flip-3" data-role="slider" data-theme="a">
		<option value="no">No</option>
		<option value="yes">Yes</option>
	</select>
</div>
]]></code></pre>

		<p>This results in a switch with the swatch "a" colors for the handle. Note that the lefthand "on" state gets the active state color.</p>
		<p>It is also possible to theme the track of the flip switch by adding the data-track-theme attribute and specifying the chosen swatch letter on the select.</p>
		<p>Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="flip-5">Flip switch:</label>
	<select name="flip-5" id="flip-5" data-role="slider" data-theme="a" data-track-theme="b">
		<option value="no">No</option>
		<option value="yes">Yes</option>
	</select>
</div>
]]></code></pre>

	</longdesc>
	<added>1.0</added>
	<options>
		<option name="classes" type="Object">
			<default> {
				"ui-slider-track": "ui-shadow-inset ui-corner-all",
				"ui-slider-input": "ui-shadow-inset ui-corner-all"
			}</default>
			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		</option>
		<xi:include href="../includes/widget-option-defaults.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="highlight" default="false" example-value="true">
			<desc>Sets an active state fill on the track from the left edge to the slider handle when set to "true".

			</desc>
			<type name="Boolean" />
		</option>
		<xi:include href="../includes/widget-option-initSelector.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-mini.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-theme.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="trackTheme" default="null, inherited from parent" example-value='"a"'>
			<desc>Sets the color scheme (swatch) for the slider's track, specifically. It accepts a single letter from a-z that maps to the swatches included in your theme.

				<p>Possible values: swatch letter (a-z).</p>
				<p>This option can be overridden in the markup by assigning a data attribute to the input, e.g. <code>data-track-theme="a"</code>.</p>
			</desc>
			<type name="String" />
		</option>
	</options>
	<events>
		<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<event name="start">
			<desc>triggered when there's an initial interaction with the slider. Includes drags and taps.</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
		</event>
		<event name="stop">
			<desc>triggered at the end of an interaction with the slider. Includes drags and taps.</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
		</event>
	</events>
	<methods>
		<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<method name="refresh">
			<desc>update the slider.
				<p>If you manipulate a slider via JavaScript, you must call the refresh method on it to update the visual styling.</p>
			</desc>
		</method>
	</methods>
	<example>
		<desc>A basic example of a slider.</desc>
		<html><![CDATA[<div data-role="header">
		<h1>jQuery Mobile Example</h1>
	</div>
	<div role="main" class="ui-content">
		<label for="slider-0">Input slider:</label>
		<input type="range" name="slider-0" id="slider-0" value="60" min="0" max="100">
	</div>]]></html>
	</example>
	<example>
		<desc>A basic example of a flip toggle switch.</desc>
		<html><![CDATA[
<div data-role="page" id="page1">
	<div data-role="header">
		<h1>jQuery Mobile Example</h1>
	</div>
	<div role="main" class="ui-content">
		<label for="flip-0">Select slider:</label>
		<select name="flip-0" id="flip-0" data-role="slider">
			<option value="off">Off</option>
			<option value="on">On</option>
		</select>
	</div>
</div>
]]></html>
	</example>
	<category slug="widgets"/>
</entry>