dhtmlxSlider Guide and Code Samples

1. Introduction

1.1 Scope of the Document

This document describes dhtmlxSlider component, defines its features and global parameters. This documentation is created to give users full understanding of every feature of this component, and also to enable users to implement this component quickly and easily.

1.2 Target Readers

Target readers are users (developers).

2. What is dhtmlxSlider


dhtmlxSlider component allows users to implement vertical or horizontal slider bars into web pages. The component is really easy to implement and customize. There is a number of predefined skin available, but there is no limitations in creating any other custom appearance. Complete JavaScript API is provided to help users to save time on configuring.

With dhtmlxSlider, the users gain the following possibilities:

2.1 Main Features

2.2 Supported Browsers

3. Initialization of dhtmlxSlider

dhtmlxSlider can be initialized on page using one of the following initialization schemes:


The first things that need to be done for any type of dhtmlxSlider's initialization are the following:

<head>   
    <link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxslider.css">
    <script src="
[full path to this file/dhtmlxcommon.js"></script>

    <script src="[full path to this file]/dhtmlxslider.js"></script>    

</script>

3.1 Setting Image Path

The following ways of setting image path are available in dhtmlxSlider:


<script>
    sld.setImagePath("[full path to this category]/codeabse/imgs/"); // should be used after creation of slider's object
</script>
<head>
    ...
    <script src="[full path to this file]/dhtmlxslider.js"></script>
    <script>window.dhx_globalImgPath="[full path to this category]/codebase/imgs/";</script> // sets image path
</head>

3.2 Minimal Initialization

The user needs to create an object where dhtmlxSlider will be placed later. In this example the object is a <div> element on page which is placed in the <body> tag:
<div id="slider"></div>
The next step is to create a new dhtmlxSlider and place it after the <div> element (object) that we've just created:
<script>
   var sld = new dhtmlxSlider(container, size);
</script>
The parameters in the above mentioned code string are the following:


The last command that should be called in order to initialize the component is:
<script>
    sld.init();
</script>
When the page is loaded, the slider will be displayed on page with the minimum value set in it.

3.3 Extended Initialization

Creating a Slider with extended initialization, the user should call the same commands described in Minimal initialization.

The code for extended initialization should be like this:
<script>
    var sld = new dhtmlxSlider(container, size, skin, vertical, min, max, value, step);
    sld.init();
</script>
The parameters the user should indicate are as follows:


When the page is loaded, the slider will be displayed on page with the current value set in it.

3.4 Initialization by Object Notation

Initialization of this kind is similar to the above mentioned types. The only difference is that the second parameter is an object containing all the initialization parameters:
<div id="slider"></div>

<script>
    var sld = new dhtmlxSlider("slider", {
            size:100,           
               skin: "ball",
               vertical:false,
               step:1,
               min:1,
               max:100,
               value:50
           
        });
    sld.init();
</script>

3.5 Inline Initialization

This type of initialization presupposes that the Slider can be created without indicating the object for it. It should be noted that the slider will be created at the same place where the initialization script was called:
<script>
    var sld = new dhtmlxSlider(null, 300);
        //or
    var sld = new dhtmlxSlider(null, {
            size:100,           
            skin: "ball",
            vertical:false,
            step:1,
            min:1,
            max:100,
            value:50           
        });
    sld.init();
</script>

3.6 Initialization from HTML Input

The user can initialize the Slider from some existing HTML input. The thing that needs to be done for that is adding dhtmlxSlider's CSS class to it. The user should do the following:

<head>
    <script src="[full path to this file]/codebase/ext/dhtmlxslider_start.js"></script>
</head>

<input class="dhtmlxSlidername="slider" skin="ball" style="width:200px" min="1" max="200" step="1" value="10">
The parameters of the input element the user should indicate are the following:

4. dhtmlxSlider Configuration

4.1 Setting Skin

The skin can be set for dhtmlxSlider in one of the following ways:


<script>
    var sld = new dhtmlxSlider("slider", 100, "ball", ...);
        //or
    var sld = new dhtmlxSlider("slider", {                    
               skin:
"ball",
              
...
        
});
</script>

<script>

    sld.setSkin(skin);

</script>
Note: to set the default skin, the user should write an empty string as the parameter for setSkin() method.

4.1.1 Available Skins


The following skins are available for this component:










4.3 Setting Minimum/Maximum/Current Values

Two ways are responsible for setting minimum, maximum, and current values in dhtmlxSlider:

<script>
    var sld = new dhtmlxSlider(container, size, skin, vertical, min, max, value, ...);
        //or
    var sld = new dhtmlxSlider("slider", {                    
               min
:1,
            max:100,
            value: 50,
              
...
        
});
</script>
<script>
     sld.setMin(10); // leftmost position
     sld.setMax(10); // rightmost position
     sld.setValue(50); // current position
</script>
The current slider's value can be got with the help of method getValue():
<script>
     var value = sld.getValue(); // returns current slider's position
</script>

4.4 Setting Step

It is possible to set minimal allowed difference between slider's values (step) in the following way:

<script>
    var sld = new dhtmlxSlider(container, size, skin, vertical, min, max, value, step);
        //or
    var sld = new dhtmlxSlider("slider", {                    
               step:
1,
              
...
        
});
</script>
<script>
     sld.setStep(1);
</script>

4.5 Setting Tooltip

There is a method that enables/disables slider's tooltip easily:

<script>

    sld.enableTooltip(true|false); // true by default

</script>

This tooltip displays changeable values of the slider when the user moves the slider's thumb.

4.6 Linking Slider to Object

The slider can be linked to some objects on page. In this case, linkTo() method is used. The slider can be linked to:

<script>
    sld.linkTo(pbjectId);
</script>
The example provided below shows the way how the slider can be linked to an HTML input:
<input type="text" id="input">

<script>
    var sld = new dhtmlxSlider(null, 500);
    sld.linkTo("input");
    sld.init();
</script>

4.7 Setting Priority

dhtmlxSlider allows to set user's input prior to slider's step if the slider is linked to an input. So, when the user types some value in the input, slider's value will be set the closest to the one indicated by user in the input. setInputPriority() method is responsible for it.
<script>
    sld.setInputPriority(true|false); // true by default
</script>

4.8 Setting Stepping Mode

Method setSteppingMode() sets slider's stepping mode which can be described as follows: on selecting some slider's value by a mouse pointer, this mode (if switched on) moves slider's thumb one step further in the direction of the selection.
<script>
    sld.setSteppingMode(true|false); // false by default
</script>

5. Event Handling

The following events are available in dhtmlxSlider:

5.1 Attaching Event Handler

The user can add any user-defined handler to any of the available events.

To do this, the user can use attachEvent() method that sets the function called when specified event occurs. It has the following parameters:


<script>

    sld.attachEvent(evName, evHandler);

</script>

Note: the names of the events are case-sensitive.

5.2 onChange Event

This event calls user-defined handlers (if there are any) and passes the following parameters:

<script>

    sld.attachEvent("onChange",function(newValue,sliderObj){

        alert("New value is "+newValue);

    })

</script>

 

5.3 onSlideEnd Event

This event calls user-defined handlers (if there are any) and passes the following parameter:

<script>
    sld.attachEvent("onSlideEnd",function(sliderValue){
        //some code
    })
</script>