CARPE Slider v3.0

BY TOM HERMANSSON SNICKARS

This is the full documentation of the CARPE Slider. The four sections below explain how to install the slider files, write the html mark-up, style sliders with css and use the JavaScript objects and methods.

The test page has more slider examples to play with.

The main page has information on licenses, downloading and more.

How to install

  1. Download the files from the main page.
  2. Uncompress the files (if applicable) and place them in your project directory. Only the JavaScript file carpe_slider.js, and the css file carpe_slider.css are needed for the sliders to work. You may place the script file and stylesheet file in any directory, but make sure they can be accessed from your web pages or application.
  3. To make the slider script work you need to reference the files from your page(s) or app(s). The stylesheet goes in the head of the document:
    <link href="my_styles_path/carpe_slider.css"
        rel="stylesheet"/>

    Make sure you adjust the path (my_styles_path above) to your directory structure and the file's location.
  4. If you have a stylesheet that should override the slider default stylesheet, you should insert the link after the CARPE Slider default stylesheet:
    <link href="my_styles_path/my_slider.css"
        rel="stylesheet"/>
  5. To make the sliders look and feel better in Internet Explorer 6, 7 and 8 you may add the following optional code to the top of your page:
    <!--[if lt IE 8]><html class="lt-ie8" lang="en"><![endif]--> <!--[if lt IE 9]><html class="lt-ie9" lang="en"><![endif]--><!--[if gt IE 8]><!--><html lang="en"><!--<![endif]-->
    Change the lang attribute for other languages than English.
  6. Add a script tag referencing the slider script at the end of the page just before the body end tag:
    <script src="carpe_slider.js"></script>
  7. Make sure you have a document type declaration at the top of your page to trigger strict mode in browsers:
    <!DOCTYPE html>

The html mark-up

With the CARPE Slider script installed in your page or app, input elements will be converted to CARPE Sliders if they are of type range and the data-carpe-slider attribute is not equal to no or false.

The following mark-up produces a slider with the default behavior. Only the type attribute needs to be set.

<input type="range"/>

For users that disable JavaScript in their browsers, you may want to include one or more noscript tags in your code:

<input type="range"/>
<noscript>Enable JavaScript to see the CARPE Slider.</noscript>

Enable JavaScript to see the CARPE Slider.

Note that older browsers will produce a CARPE Slider if JavaScript is enabled, but otherwise only show a text input. To cover those cases you may want to include some additional guidance:

<input type="range"/>
<noscript>Enable JavaScript to see the CARPE Slider, or enter a whole number between 0 and 100.</noscript>

Enable JavaScript to see the CARPE Slider, or enter a whole number between 0 and 100.

The CARPE Slider uses the same html attributes as the default range input, but there are also a few custom attributes for extra functionality. The following attributes has an effect on the slider behavior:

The following attributes are deprecated and no longer available in the latest version:

The id attribute should be set to a unique value if your slider needs to be accessible by other form elements, sliders or scripts.

The name attribute is important if the slider value shall be sent to the server.

The type attribute needs to be set to range for the slider script to be activated.

The class attribute may be used in the normal way to specify one or more css classes, but it's also used to specify the orientation of the slider. Adding the class name vertical will make the slider orientation vertical. Leaving it out will produce a horizontal slider, which is the default.

Individual styling of the slider, including its dimensions, may be done with the style attribute, but styling with a separate stylesheet is recommended. Read more about styling below.

As with regular input elements, the disabled attribute disables the slider. The styling of disabled sliders can be done with css. Read more about styling below.

The value of the tabindex attribute has the same effect as for any other form element.

The min attribute specifies the start value for the slider. For a CARPE Slider the min value does not have to be lower than the max value. A min value greater than the max value produces a reversed slider – a slider with the higher value to the left (or at the bottom for vertical sliders). The default value for the min attribute is 0 (zero).

The max attribute specifies the end value for the slider. The default value for the max attribute is 100.

The step attribute works as for regular range inputs. It specifies the value increments the slider should snap to, and the value increment/decrement for keyboard control with arrow keys. The default value for the snap attribute is the value equivalent of one pixel, which in practice means no snapping, and movement of one pixel with the arrow keys.

The value attribute works as for regular input elements. It specifies the default and initial value. If no value attribute is set, the slider knob/handle will be positioned in the middle of the slider, and the slider value adjusted accordingly.

The data-carpe-slider attribute specifies whether a normal range input element or a CARPE Slider, the default behavior, should be displayed. A value of no or false results in an input with the browser's regular style.

The data-carpe-decimals attribute specifies how many decimals the slider value should be rounded off to.

The data-carpe-targets attribute specifies target elements for the slider. The attribute value is a space-separated list of target id:s. If the target has a value property (like an input element), its value will be set to the value of the slider. If the target is a regular html element, the innerHTML property will be set to the slider value. With the pro version of the CARPE Slider, there is a third alternative; If the target has a method named update, that method will be called with the slider value as the argument.

The data-carpe-link-title attribute specifies the help text of the title attribute for the CARPE link, in non-touch devices, like desktop computers. You may want to use this attribute if your page or app is in a different language than English. In the pro version the link is optional and fully customizable.

The data-carpe-link-title-touch attribute specifies the help text of the title attribute for the CARPE link, in touch devices. You may want to use this attribute if your page or app is in a different language than English and aimed at touch device users. In the pro version the link is optional and fully customizable.

The following mark-up generates a disabled slider:

<input type="range" disabled="disabled"/>

The mark-up below does not trigger the slider script. The resulting input is the same as in a browser with JavaScript disabled. A modern browser will show its default range input element. An older browser will show a text input element:

<input type="range" data-carpe-slider="no"/>


The mark-up below produces a vertical slider:

<input type="range" class="vertical"/>


The following is an example with all other relevant attributes set:

<input
    id="my_first_slider"
    name="my_first_slider"
    type="range"
    style="width: 300px;"
    tabindex="0"
    min="0"
    max="3000"
    step="100"
    value="0"
    data-carpe-decimals="2"
    data-carpe-targets="my_first_target"
    data-carpe-link-title="DON'T PANIC"
    data-carpe-link-title-touch="Touch me!" />

The following p element acts as a target element for the slider above:

<p id="my_first_target"></p>

Try adjusting the value with the slider!

Styling with css

The default slider stylesheet specifies css properties for the following classes and their different pseudo-classes, like :hover and :focus:

The following mark-up illustrates the html element tree that makes up a CARPE Slider:

<div class="carpe-slider-box">
    <div class="carpe-slider-knob"></div>
    <input class="carpe-slider-hidden"/>
    <a class="carpe-slider-panel">
        <div class="carpe-slider-track"></div
    </a>
    <a class="carpe-slider-link"></div>
</div>

To style your sliders you could change the default stylesheet, but it's probably a good idea to just override the default properties instead to make it easier to revert back to the default.

Some properties and their values are critical for the sliders to work. Make sure you test the sliders properly if you change any of the following properties:

Here is a simple example of how to override css properties in a separate stylesheet (has to be loaded after the default stylesheet):

<style>
.carpe-slider-box .carpe-slider-panel,
.carpe-slider-box:hover .carpe-slider-panel,
.carpe-slider-box:focus .carpe-slider-panel {
    background: none;
    border-color: white;
}
</style>

<input type="range"/>

You can also style independent sliders or groups of sliders using the id and class attributes respectively. The id and class attributes are copied from the original input element to the carpe-slider-box element automatically. The following two examples demonstrates how this could be written in your css:

<style>
.my-slider-class .carpe-slider-panel,
.my-slider-class:hover .carpe-slider-panel,
.my-slider-class:focus .carpe-slider-panel {
    border-color: red;
}
</style>

<style>
#my-slider-id .carpe-slider-panel,
#my-slider-id:hover .carpe-slider-panel,
#my-slider-id:focus .carpe-slider-panel {
    border-color: green;
}
</style>

The JavaScript objects & methods

If your page is just a static html page (even if it's generated by the server) with some sliders (with or without a form), you may skip this section. It is aimed at developers, with some JavaScript experience, who need to have interaction between sliders and other code, or take advantage of the CARPE convenience methods.

The CARPE.init method starts by finding all input elements in the page. It then makes a slider object for every input element of the range type (where the data-carpe-slider attribute is neither set to no nor false). The slider constructor replaces the range input with an html div element, the slider box, containing a hidden input element, the slider panel, the slider link and the slider knob. Additionally, the slider panel has the slider track as a child element. This method call can, and should, be repeated later if new sliders are added by simply inserting html input elements of type range.

No variable is left in the global JavaScript namespace, and no native objects are changed, but the CARPE object, and slider objects with their class methods, may be accessed through any slider element in the page:

The CARPE object (CARPE) is the main application object, and it has some general convenience methods and properties, and the sliders object. Here is a list of some properties and methods of the CARPE object that may be useful for your own code:

Before the CARPE methods can be used you need to get hold of the CARPE object, which is referenced from each slider object, but not exposed to the global namespace by default. Example:

var myCARPE =
getElementsById('my_slider').slider.CARPE;
myCARPE.camelize('my-long-class-name');
// 'myLongClassName'

The sliders object (CARPE.sliders) holds methods and properties for all sliders as a group. It's a member of the CARPE object. The following methods and properties may be useful in your own code:

The slider class: Once you have a reference to a slider object there are several methods and properties that may be of use in your own code. Some are listed below. Read the source code to find all properties and methods.

The slider constructor is a private function within the CARPE Slider code. Use the CARPE.sliders.init() method instead, after inserting an input element in the document.

Useful slider class methods:

Useful slider class properties: