Configure RangeSelector

This guide contains detailed instructions on how to configure the dxRangeSelector widget. You will learn how to define the dxRangeSelector's scale, customize the default appearance to your requirements and work with the currently selected range. As a result, we will get a widget that allows us to choose a time period. For instance, this widget will be useful in an online ticket agency, to filter a list of possible flights according to the time range selected by a client.

You can watch video lessons on ChartJS widgets. Here is the video that will allow you to get started with the range selector: ChartJS: Getting Started with dxRangeSelector.

Create a RangeSelector

Begin by creating an HTML file. Then, add references to the required libraries (see the [Add Libraries](/Documentation/Guide/Data_Visualization/Basics/Create_a_Widget/#AddLibraries) tutorial).

<!--HTML--><!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <script type="text/javascript" src="jquery-1.9.1.min.js"></script>
        <script type="text/javascript" src="knockout-2.2.1.js"></script>
        <script type="text/javascript" src="globalize.min.js"></script>
        <script type="text/javascript" src="dx.chartjs.js"></script>
    </head>
    <body></body>
</html>

There are several approaches to creating a ChartJS widget. And this page will utilize the jQuery approach. Refer to the Add a Widget tutorial to go over the remaining approaches.

Add a div element. It will be a container for the dxRangeSelector widget.

HTML
<body>
    <div id="rangeSelectorContainer" style="height:170px;max-width:600px;margin: 0px auto"></div>
</body>

Create the dxRangeSelector widget within the added container.

HTML
<head>
    <!-- ... -->
    <script type="text/javascript">
        $(function () {
            $("#rangeSelectorContainer").dxRangeSelector({});
        })
    </script>
</head>

Run this code and you will see an empty dxRnageSelector widget, in which the scale must now be specified.

Configure a Scale

Let's define a scale. According to the task that we declared in the beginning, it will be a time scale for an entire day.

To define a scale, use the scale configuration object. The following code demonstrates how to set the start and end scale values.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    scale: {
        startValue: new Date(2012, 8, 29, 00,00,00),
        endValue: new Date(2012, 8, 29, 24,00,00)                           
    }
});

The major ticks (those that have labels) and minor ticks (ticks between the major ticks) are arranged automatically. Let's make the minor tick interval fixed so that it always equals 'hour' when the size of the dxRangeSelector container changes.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    scale: {
        //...
        minorTickInterval: 'hour',                      
    }
});

If you now run this code, you will see an entire day on a scale. Try moving the sliders. They are snapped to ticks. Thus, you can select a range multiple of an hour. At the same time, there are no labels for each scale value, since it would not look very nice to have overlapped tick labels. The only thing that is unnecessary on the scale is the marker that indicates a transition between two days. We can set a flag to not show scale markers using the scale's marker configuration object. See the following code.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    scale: {
        //...
        marker: { visible: false }
    }
});

Let's set an initial range to be selected when the dxRangeSelector is initialized. We will use a range between 11AM and 5PM, the most common range for traveling. To do this, use the selectedRange configuration object.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    //...
    selectedRange : { 
        startValue: new Date(2012, 8, 29, 11,00,00),
        endValue: new Date(2012, 8, 29, 17,00,00),
    }
});

Finally, let's set an appropriate format for the scale labels and slider markers. To do this, we will use the format property.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    //...
    scale: {
        //...
        label: {format: 'shortTime'}
    },
    sliderMarker: {format: 'shortTime'}
});

The scale is now fully defined.

Customize the Appearance

If you wish to change the background image used by default, use the background configuration object as shown below.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    //...
    background: {
        image: {                            
            url: 'RangeImage.png',
            location: 'full'
        }
    }   
}); 

As you can see in the code above, the location option is set to full so that the image is scaled according to the dxRangeSelector's background size. In this connection, the widget's height must be set so that the widget's height-to-width ratio is equivalent to the image's height-to-width ratio. This can be done by setting the widget's width to a specific value. The following code demonstrates how to set the widget's width to the parent container's width, and how to calculate the widget's height based on the image's aspect ratio.

JavaScript
var clientWidth = $('#rangeSelectorContainer').width();
$("#rangeSelectorContainer").dxRangeSelector({
    size: {
       height: (clientWidth - 2*65) / 4 + 20+30
    },
    scale: {
        //...
        placeholderHeight: 20
    },
    sliderMarker: {
        placeholderSize: {
            width: 65,
            height: 30
        }
    },
    margin: {
        top: 0,
        bottom: 0,
        left: 0,
        right: 0
    },
    //...
});

Since the background width is calculated by subtracting two slider marker widths from the container width, set a fixed value for the slider marker width, and zero for the widget's left and right margins. The background height is calculated by subtracting the scale height and the slider marker height from the container's height; therefore, fixed values for the scale height and slider marker height must be set, along with zero as the widget's top and bottom margins.

Get the Selected Range

The capability to choose the currently selected range is not sufficient for our task that we described in the beginning. We need to get the currently selected range after it has been changed to filter the list of the appropriate flights. However, as we do not introduce a full page in this guide, but rather the dxRangeSelector only, we will demonstrate how to get the currently selected range in a simple task.

Let's add a span to the HTML page to display the currently selected range.

HTML
<span id='selectionSpan' />

To get and use the currently selected range after it has been changed, define the selectedRangeChanged callback function within the dxRangeSelector's configuration object, as shown below.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    //...
    selectedRangeChanged: function(selectedRange) {     
        $('#selectionSpan').html('SelectedRange: (' +
            Globalize.format(selectedRange.startValue, 't') +
            ', ' + Globalize.format(selectedRange.endValue, 't') + ')');
    }
});

As you can see, the selectedRangeChanged function has a parameter that represents the currently selected range. To get the start and end values of this range, use the startValue and endValue properties of the object passed as the parameter.