jQRangeSlider - jQuery UI range selection slider

jQRangeSlider is a powerful slider for selecting value ranges, supporting dates and more.

Source: ghusse.github.io

1. INCLUDE CSS AND JS FILES

<link rel="stylesheet" href="css/iThing.css" type="text/css" />
<script src="jquery.js"></script>
<script src="jquery-ui.custom.js"></script>
<script src="jQRangeSlider-min.js"></script>

2.  HTML

<div id="slider"></div>
<div id="dateSlider"></div>
<div id="editSlider"></div>

3. JAVASCRIPT

$("#slider").rangeSlider();
$("#dateSlider").dateRangeSlider();
$("#editSlider").editRangeSlider();

4. OPTIONS

Get and set options

Options can be set in constructor or after initialization.

// Set option value in constructor
$("#slider").rangeSlider({
  bounds: {min: 0, max: 100}
});
// Change options after slider creation
$("#slider").rangeSlider("option", "bounds", {min: 10, max: 90});
// Get option value
var bounds = $("#slider").rangeSlider("option", "bounds");
// Set date option
$("#dateSlider").dateRangeSlider(
  "option",
  "bounds",
  {
    min: new Date(2012, 0, 1),
    max: new Date(2012, 11, 31)  
});

Arrows

The option arrows lets you remove scrolling arrows on both sides of the slider.

Bounds

The option bounds allows you to modify min and max values of the slider.

Default values

The option defaultValues lets you specify values selected by default on construction.

Delay out

Option delayOut lets you specify the duration labels are shown after the user changed its values..

Duration in/out

Option durationIn lets you specify the animation length when displaying value labels. Similarly, durationOut allows to customize the animation duration when hiding those labels.

Enabled

The option enabled allows you to configure a read-only slider.

Formatter

The option formatter lets you customize displayed label text.

Range

The option range lets you specify minimum and/or maximum range length. For instance, let's consider you want the user to choose a range of dates during 2012. You can constraint people to choose at least 1 week during this period. Similarly, you also can constraint the user to choose 90 days at maximum.

When this option is activated, the slider constraints the user input. When minimum or maximum value is reached, the user cannot move an extremity further to shrink/enlarge the selected range.

Ranges in date sliders have to be set using an object, specifying at least one property in the list below.

• years
• months
• weeks
• days
• hours
• minutes
• seconds

Scales

The option scales lets you add a ruler with multiple scales to the slider background.

The option scales requires an array of objects. Each object represents the configuration of one level.

Scale configuration object can contain 5 functions:

The function first(min, max) [optional]

Must return the ruler first value.

It gives you a way to make the ruler start after the slider minimum. By default, this method returns the slider minimum value.

The function next(value)

Must return the next value. This method is required.

Be sure to return a valid date object when using scales with date sliders.

The function label(value, nextValue):string [optional]

Must return the displayed text, for a given interval.

You can return an empty string or null if you don't want labels to be displayed. By default, this method returns value.toString().

The method stop(value):boolean [optional]

Return true to stop the scale generating ticks from a given value.

This method returns false by default.

The function format(tickContainer, tickStartValue, tickEndValue) [optional]

Can be used to customise the tick container DOM element. First argument is passed as a jQuery object.

Step

The option step allows to customize values rounding, and graphically render this rounding. Considering you configured a slider with a step value of 10: it'll only allow your user to choose a value corresponding to minBound + 10n.

Steps in date sliders have to be set using an object, specifying at least one property in this list below.

• years
• months
• weeks
• days
• hours
• minutes
• seconds

Symmetric positionning

The option symmetricPositionning changes the way handles are positionned on the slider. This option is usefull when customizing how the slider is displayed.

Use this option when you want to show handles and make them clearly select the range.

Type

The option type allows to specify input types in edit slider. Possible values are text (default) and number.

Value labels

The option valueLabels lets you specify a display mode for value labels: hidden, shown, or only shown when moving. Possible values are: show, hide and change.

Wheel mode

The option wheelMode allows to use the mouse wheel to scroll (translate) or zoom (enlarge/shrink) the selected area in jQRangeSlider.

Wheel speed

The option wheelSpeed lets you customize the speed of mouse wheel interactions. This parameter requires the wheelMode to be set.

5. EVENTS

Binding events

You can attach event handlers to the slider using jQuery functions such as bind() or on().

// For earlier versions if jQuery, but still supported

$("#slider").bind("valuesChanging", function(e, data){

console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);

});

// Preferred method

$("#slider").on("valuesChanging", function(e, data){

console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);

});

// Possible use, if sliders are constructed/destroyed many times

$(document).on("valuesChanging", ".ui-rangeSlider", function(e, data){

console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);

});

Values changing

Use the event valuesChanging if you want to intercept events while the user is moving an element in the slider.

$("#slider").bind("valuesChanging", function(e, data){

console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);

});

Values changed

Use the event valuesChanged when you want to intercept events once values are chosen. This event is only triggered once after a move.

$("#slider").bind("valuesChanged", function(e, data){

console.log("Values just changed. min: " + data.values.min + " max: " + data.values.max);

});

User values changed

Like the valuesChanged event, the userValuesChanged is fired after values finished changing. But, unlike the previous one,userValuesChanged is only fired after the user interacted with the slider. Not when you changed values programmatically.

// This event will be fired

$("#slider").bind("valuesChanged", function(e, data){

console.log("Will be executed");

});

// This event will not ne fired

$("#slider").bind("userValuesChanged", function(e, data){

console.log("Will NOT be executed");

});

// Changing values programmatically

$("#slider").rangeSlider("values", 10, 20);

6. METHODS

Executing methods

Methods on sliders (as all jQuery UI widgets) have to be called in a special way. See examples below.

Basic slider

// Use the slider method to call methods

// First argument: method name

// Next arguments: method arguments

$("#slider").rangeSlider("values", 10, 20);

Edit slider

// Use the slider method to call methods

// First argument: method name

// Next arguments: method arguments

$("#slider").editRangeSlider("values", 10, 20);

Date slider

// Use the slider method to call methods

// First argument: method name

// Next arguments: method arguments

$("#slider").dateRangeSlider("values", new Date(2012, 0, 1), new Date(2012, 0, 31));

Bounds

The method bounds([min, max]) gets or sets the bounds. You can get and change bounds with this method or with the boundsoption.

bounds() accepts zero or two arguments. If both arguments are provided, then this method initializes slider's bounds to given values. In both cases, it returns bounds values.

Get values

// Basic slider

var basicSliderBounds = $("#slider").rangeSlider("bounds");

console.log(basicSliderBounds.min + " " + basicSliderBounds.max);

 

// Edit slider

var editSliderBounds = $("#editSlider").editRangeSlider("bounds");

console.log(editSliderBounds.min + " " + editSliderBounds.max);

 

// Date slider

var dateSliderBounds = $("#dateSlider").dateRangeSlider("bounds");

console.log(dateSliderBounds.min.toString() + " " + dateSliderBounds.max.toString());

Set values

// Basic slider

$("#slider").rangeSlider("bounds", 10, 20);

 

// Edit slider

$("#editSlider").editRangeSlider("bounds", 20, 100);

 

// Date slider

$("#dateSlider").dateRangeSlider("bounds", new Date(2012, 0, 1), new Date(2012, 0, 31));

Destroy

The method destroy() allows you to remove a slider from your page. It releases memory and removes all DOM elements added by the slider constructor.

Enable / disable

The methods enable and disable lets you enable or disable a slider. When a slider is diabled, user can't modify its values.

Min / max

Methods min([value]) and max([value]) can be used to get or set minimum/maximum selected value in the slider.

Both methods accept one optional argument. When used, this value is set as a new minimum/maximum value for the selected range. This methods always return new value for the minimum/maximum value of selected range.

Get values

// Basic slider

var basicSliderMin = $("#slider").rangeSlider("min");

console.log(basicSliderMin);

 

// Edit slider

var editSliderMin = $("#editSlider").editRangeSlider("min");

console.log(editSliderMin);

 

// Date slider

var dateSliderMax = $("#dateSlider").dateRangeSlider("max");

console.log(dateSliderMax.toString());

Set values

// Basic slider

$("#slider").rangeSlider("min", 10);

 

// Edit slider

$("#editSlider").editRangeSlider("min", 20);

 

// Date slider

$("#dateSlider").dateRangeSlider("max", new Date(2012, 1, 1));

Resize

The method resize() can be used to update slider size after a change in parent's size. This method is automatically called on window resize.

Scroll left/right

Methods scrollLeft(pixels) and scrollRight(pixels) allow you to simulate click on slider arrows. You can adjust speed by increasing/decreasing the amount.

Values

The method values([min, max]) can be used for getting current selected values, and setting new values.

Get values

// Basic slider

var basicValues = $("#slider").rangeSlider("values");

console.log(basicValues.min + " " + basicValues.max);

 

// Edit slider

var editValues = $("#editSlider").editRangeSlider("values");

console.log(editValues.min + " " + editValues.max);

 

// Date slider

var dateValues = $("#dateSlider").dateRangeSlider("values");

console.log(dateValues.min.toString() + " " + dateValues.max.toString());

Set values

// Basic slider

$("#slider").rangeSlider("values", 10, 20);

 

// Edit slider

$("#editSlider").editRangeSlider("values", 20, 100);

 

// Date slider

$("#dateSlider").dateRangeSlider("values", new Date(2012, 0, 1), new Date(2012, 0, 31));

Zoom in/out

Methods zoomIn(speed) and zoomOut(speed) allow you to enlarge/reduce selected range in the slider.