Dojo: The Definitive Guide

Slider

While a slider may not be a native HTML form control, there can be little dispute about how useful sliders can be for highly visual interfaces. Whether your goal is to adjust the transparency for an image, adjust the amount of a particular color in a custom color combination, or resize some other control on the screen, a slider can help you do it in a very intuitive manner. Dijit offers both horizontal and vertical sliders.

Tip

The Slider dijit is an especially slick piece of engineering. Like some of the other dijits, it keeps track of the current value via a hidden form value so that when you submit a form, the value is passed over to the server just like any other form field.

To get all of the various Slider machinery into your page, simply do a dojo.require("dijit.form.Slider"). In addition to VerticalSlider and HorizontalSlider, you also get the supporting classes for rules and labels. Let's start with something simple and gradually add some complexity so that you get a better feel for exactly how customizable this fantastic little widget really is.

HorizontalSlider

Suppose that as a caffeine junkie, you want to create a horizontal slider that denotes caffeine levels for various beverages. Your first stab at getting a plain vanilla slider into the page might be something like the Example 13-13, remembering to first require dijit.form.Slider into the page.

Example 13-13. HorizontalSlider (Take 1)

<div dojoType="dijit.form.HorizontalSlider" name="caffeine"
    value="100"
    maximum="175"
    minimum="2"
    style="margin: 5px;width:300px; height: 20px;">

    <script type="dojo/method" event="onChange" args="newValue">
        console.log(newValue);
    </script>
</div>

To summarize, the code created a slider without any kinds of labels whatsoever; the slider displays values ranging from 2 through 175 with the dimensions provided by the inline style. The default value is 100, and whenever a change occurs, the onChange method picks it up and displays it to the console. Note that clicking on the slider causes its value to move to the click point. So far, so good.

To further refine the slider, let's remove the buttons that are on each end of it by adding showButtons="false" as an attribute and adding a HorizontalRule and some HorizontalRuleLabels to the top of the slider. Everything you need was already slurped into the page, so no additional resources are required; we pull in the dojo.number module, however, to facilitate formatting to the console.

Just add some more markup into the body of the existing slider, as shown in Example 13-14.

Example 13-14. HorizontalSlider (Take 2)

<div dojoType="dijit.form.HorizontalSlider" name="caffeine"
    value="100"
    maximum="175"
    minimum="2"
    showButtons="false"
    style="margin: 5px;width:300px; height: 20px;">

    <script type="dojo/method" event="onChange" args="newValue">
        console.log(dojo.number.format(newValue,{places:1,pattern:'#mg'}));
    </script>

    <ol dojoType="dijit.form.HorizontalRuleLabels" container="topDecoration"
        style="height:10px;font-size:75%;color:gray;" count="6">
    </ol>

    <div dojoType="dijit.form.HorizontalRule" container="topDecoration"
        count=6 style="height:5px;">
    </div>
</div>

Presto! The slider is already looking much sharper with the addition of some ticks to break up the space and some percentage labels. Note that it is not necessary to have a one-to-one correspondence between the rules and the rule labels, but in this case, it works out quite nicely. Additionally, the attribute container used an enumerated value, topDecoration, defined by the slider to place the rules and labels.

Although the slider contains a percentage rating, it would be nice to bring in some domain specific data for the bottom of the slider. The basic pattern is the same as before, except that we'll use the slider's bottomContainer instead of its topContainer. However, instead of relying on the dijit to produce some bland numeric values, we provide the contents of the list ourselves in Example 13-15, including explicit <br> tags in multiword beverages to keep the display looking sharp. Figure 13-9 shows the result.

Example 13-15. HorizontalSlider (Take 3)

<div dojoType="dijit.form.HorizontalSlider" name="caffeine"
    value="100"
    maximum="175"
    minimum="2"
    showButtons="false"
    style="margin: 5px;width:300px; height: 20px;">

    <script type="dojo/method" event="onChange" args="newValue">
        console.log(newValue);
    </script>
    <ol dojoType="dijit.form.HorizontalRuleLabels" container="topDecoration"
        style="height:10px;font-size:75%;color:gray;" count="6">
    </ol>

    <div dojoType="dijit.form.HorizontalRule" container="topDecoration"
        count=6 style="height:5px;">
    </div>

    <div dojoType="dijit.form.HorizontalRule" container="bottomDecoration"
        count=5 style="height:5px;">
    </div>

    <ol dojoType="dijit.form.HorizontalRuleLabels" container="bottomDecoration"
        style="height:10px;font-size:75%;color:gray;">
        <li>green<br>tea</li>
        <li>coffee</li>
        <li>red<br>bull</li>
    </ol>
</div>

Figure 13-9. A HorizontalSlider

VerticalSlider

VerticalSlider works just like HorizontalSlider except that it renders along the y -axis, and you'll use leftDecoration and rightDecoration instead of topDecoration and bottomDecoration to specify container values for the rules and rule labels, as well as adjust your style to space elements out horizontally instead of vertically. Example 13-16 is the same slider, but adjusted for the vertical axis. Figure 13-10 depicts the result.

Figure 13-10. A VerticalSlider

Example 13-16. VerticalSlider

<div dojoType="dijit.form.VerticalSlider" name="caffeine"
    value="100"
    maximum="175"
    minimum="2"
    showButtons="false"
    style="margin: 5px;width:75px; height: 300px;">

    <script type="dojo/method" event="onChange" args="newValue">
        console.log(newValue);
    </script>
    <ol dojoType="dijit.form.VerticalRuleLabels" container="leftDecoration"
        style="height:300px;width:25px;font-size:75%;color:gray;" count="6">
    </ol>

    <div dojoType="dijit.form.VerticalRule" container="leftDecoration"
        count=6 style="height:300px;width:5px;">
    </div>

    <div dojoType="dijit.form.VerticalRule" container="rightDecoration"
        count=5 style="height:300px;width:5px;">
    </div>

    <ol dojoType="dijit.form.VerticalRuleLabels" container="rightDecoration"
        style="height:300px;width:25px;font-size:75%;color:gray;">
        <li>green&nbsp;tea</li>
        <li>coffee</li>
        <li>red&nbsp;bull</li>
    </ol>
</div>

Table 13-13, Table 13-14, and Table 13-15 illustrate the important facets of the dijit.form.Slider ; namely, the sliders themselves, the rules, and the labels. Remember that all of the ordinary form machinery, such as setValue, et al., is inherited and works as usual.

Table 13-13. Horizontal Slider and VerticalSlider

Name	Type	Comment
showButtons	Boolean	Whether to show increment/decrement buttons on each end of the slider. true by default.
minimum	Integer	The minimum value allowed. 0 by default.
maximum	Integer	The maximum value allowed. 100 by default.
discreteValues	Integer	The number of discrete value between the minimum and maximum (inclusive). Infinity is a continuous scale. Values greater than 1 produce a discrete effect. Infinity by default.
pageIncrement	Integer	The amount of adjustment to nudge the slider via the page up and page down keys. 2 by default.
clickSelect	Boolean	Whether clicking the progress bar causes the value to change to the clicked location. true by default.
slideDuration	Number	The time in milliseconds to take to slide the handle from 0% to 100%. Useful for programmatically changing slider values. 1000 by default.
increment( )	Function	Increments the slider by one unit.
decrement( )	Function	Decrements the slider by one unit.

Table 13-14. HorizontalRule and VerticalRule

Name	Type (default)	Comment
ruleStyle	String	The CSS class to apply to individual hash marks.
count	Integer	The number of hash marks to generate. 3 by default.
container	DOM Node	Where to apply the label in relation to the slider: topDecoration or bottomDecoration for HorizontalSlider. leftDecoration or rightDecoration for VerticalSlider.

Tip

HorizontalRuleLabel and VerticalRuleLabel inherit from HorizontalRule and VerticalRule, respectively.

Table 13-15. HorizontalRuleLabel and VerticalRuleLabel

Name	Type (default)	Comment
labelStyle	String	The CSS class to apply to text labels.
labels	Array	Array of text labels to render, evenly spaced from left-to-right or top-to-bottom. [] by default.
numericMargin	Integer	The number of numeric labels that should be omitted from display on each end of the slider. (Useful for omitting obvious start and end values such as 0, the default, and 100.)
minimum	Integer	When the labels array is not specified, this value provides the leftmost label to include as a label. 0 by default.
maximum	Integer	When the labels array is not specified, this value provides the right-most label to include. 1 by default.
constraints	Object	The pattern to use (from dojo.number ) to use for generated numeric labels when the labels array is not specified. {pattern:"#%"} by default.
getLabels	Function	Returns the labels array.