How to install
- Download the files from the main page.
- Uncompress the files (if applicable) and place them in your project directory. Only the JavaScript file
carpe_slider.js
, and the css filecarpe_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. - 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"
Make sure you adjust the path (
rel="stylesheet"/>my_styles_path
above) to your directory structure and the file's location. - 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"/> - 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 thelang
attribute for other languages than English. - 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>
- 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>
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>
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:
- id
- name
- type
- class
- style
- disabled
- tabindex
- min
- max
- step
- value
- data-carpe-slider
- data-carpe-decimals
- data-carpe-targets
- data-carpe-link-title
- data-carpe-link-title-touch
The following attributes are deprecated and no longer available in the latest version:
- stops
- data-carpe-from
- data-carpe-to
- data-carpe-zerofill
- data-carpe-orientation
- data-carpe-target
- data-carpe-source
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:
carpe-slider-box
carpe-slider-panel
carpe-slider-link
carpe-slider-track
carpe-slider-knob
vertical
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:
position
display
z-index
top
left
padding
margin
width
height
float
line-height
font-size
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:
isFunction(any_argument)
: returnstrue
if the argument is a function.position(HTML_element)
: Returns{ x: number, y: number }
representing the relative position of an element in pixels.position(HTML_element, { x: number, y: number })
: Sets the relative position of an element (in pixels) to the values of the x and y properties of the second argument respectively.scroll()
: Returns{ x: number, y: number }
representing the horizontal (x-value) and vertical (y-value) scroll position in pixels respectively.style(HTML_element, CSS_property_string)
: Accepts an html element object and a css property name. Returns the actual css value of the supplied property for the element.camelize(string[, splitter_string])
: Splits a string at each occurance of the second optional string argument (or at any '-' as the default), then makes each of the parts, except the first one, start with an upper-case character, and concatenates the parts. Returns the resulting camel-case string. Example:CARPE.camelize('string.with.dots', '.'); // 'stringWithDots'
stop(event_object)
: Stops propagation of the event and cancels its default behavior. Returnstrue
on success andfalse
for failure to stop the event.touchListener(touch_event_object)
: Accepts a touch event object. Fires the corresponding mouse event.addListener(HTML_element, event_type_string, function)
: Attaches the function as an event listener to the element object. Example:CARPE.addListener(myElement, 'mouseover', myHoverFunction);
removeListener(HTML_element, event_type_string, function)
: Detaches the function as an event listener from the element. Example:CARPE.removeListener(myElement, 'mouseover', myHoverFunction);
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:
init()
: Findsinput
elements of typerange
that has not yet been converted to CARPE sliders, and creates the sliders using the slider constructor; Adds the new slider to the collection of sliders held by theobjects
property. This method is called automatically when the page is loaded so there is no need to use it for static pages. Call this method after inserting additionalinput
elements of typerange
:CARPE.sliders.init();
update()
: Resets all sliders to their corresponding default values and slider knob positions. Use the regular Form.reset() method if you just want to reset sliders within a specific form element.objects
: An array holding theCARPE
slider objects in the document. Example:var myFirstSliderObject =CARPE.sliders.objects[0].id; // 'my_first_slider_id'
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:
enabled()
: Returnsfalse
for disabled sliders andtrue
otherwise.enabled(boolean)
: Accepts a boolean (or other truthy/falsy argument) and enables/disables the slider accordingly. Returns the slider object. Example:mySlider.enabled(false); // disabled slider
updateTargets()
: Updates the slider's targets. Returns the slider object. This method is called automatically every time the value of the slider changes.resetValue()
: Resets the slider value and slider knob position to the default. Returns the slider object.increment(integer)
: Accepts a positive (or negative) integer and increments (or decrements) the value by discrete steps accordingly. Returns the slider object.getValue()
: Returns the slider's value as a string.setValue(number)
: Sets the slider value and positions the slider knob accordingly, but if the slider has astep
attribute the value and knob position snaps to the nearest valid position. Returns the slider object.
Useful slider class properties:
decimals
: Holds the number of decimals for the slider value.form
: Holds a reference to the html form the slider is associated with or located in.box
: Holds a reference to the htmldiv
element that contains the slider component elements below. The corresponding css class name iscarpe-slider-box
.panel
: Holds a reference to the htmla
element of the slider panel. The corresponding css class name iscarpe-slider-panel
.track
: Holds a reference to the html element of the slider track. The corresponding css class name iscarpe-slider-track
. The slider track element is a child element of the slider panel element.link
: Holds a reference to the htmla
element of the slider link. The corresponding css class name iscarpe-slider-link
.knob
: Holds a reference to the htmldiv
element of the slider knob.The corresponding css class name iscarpe-slider-knob
.hidden
: Holds a reference to the html element of the hiddeninput
element with the slider value. This element also has the originalid
andname
attributes from the mark-up, and a reference to theCARPE
object and back to the slider object itself. This is useful when you need to get the slider object of a slider with a known id or when you need to use theCARPE
convenience methods. Example:var myElement = getElementsById('my_slider_id'); var mySlider = myElement.slider; var myCARPE = myElement.CARPE;