affordable web development services
| About Us | Services | Download | Order | Support | Subscribe to News Feed Follow us on Twitter Join us on Facebook |
 

Tigra Slider Control v1.1 - Documentation

Table of Contents

Description

Tigra Slider Control is a Javascript component for the website which replaces text input in web forms with easy to use draggable trackbar.

Features

Compatibility Table

Tigra Slider Control can work with any browser that supports DOM (Document Object Model). Below is the list of browsers the component was successfully tested with.

Platform Browser
MS IE Netscape Firefox/Mozilla Opera Safari AOL
Windows 95/98/ME/2000/XP 4.x+ 6.x+ 0.9.x+ 7.x+ n/a 4+
Mac OS 8.6/9 5.x+ 6.x+ 1.1+ 7.x+ 1.3.1+ n/a
KDE on Linux/FreeBSD n/a 6.x+ 1.1+ 7.x+ n/a n/a

Files

The code of the Tigra Slider Control is located in slider.js. This file must be present and properly linked to each HTML document that uses the control:

<head>
	<!-- some header data -->
	<script language="JavaScript" src="slider.js"></script>
</head>

Also the configuration structure of the slider control references two image files. There are no naming requirements for these image files, any existing images can be used with the control.

Initialization

The initialization is the JavaScript statement that creates the instance of the control with specified settings. It may look like:

<script language="JavaScript">
	new slider(A_INIT, A_TPL);
</script>

The initialization call (constructor) receives two parameters. Those are the names of the configuration structures that must be defined in the HTML document at the time the constructor is called. Second parameter is optional (see next section for more info).

In the example above the names of the configuration structures are A_INIT and A_TPL, but any other names can be used as long as they match in the structure definition and in the constructor call and also they are not JavaScript reserved words.

The slider control is positioned relatively inside the HTML element the constructor was called in (i.e table cell, div etc.).

The constructor returns the reference to the slider object that can be used for interfacing the component with custom JavaScript code. This is not the only way to get the slider's object reference. See Slider Control API section for more details.

Configuration Structures

As described in the section above the slider initialization receives the names of two initialization structures. Both structures have the same format: the comma separated list of keys:value pairs. Example:

<script language="JavaScript">
var A_INIT = {
	's_form'     : 'sampleForm',
	's_name'     : 'sampleInput',
	'n_minValue' : 0,
	'n_maxValue' : 100,
	'n_value'    : 20,
	'n_step'     : 1
};
</script>

Both structures accept the same list of configuration keys. Each required configuration key must appear in at least one of two structures. If the same key appears in both structures the value from first parameter is used. The second parameter is optional and can be omitted if all configuration data is moved to first configuration structure.
The reason for splitting the configuration in two structures is the improved maintenance of multiple instances of the control. All shared settings can be moved out of the individual configuration structures and into the separate structure which then can be refereed in multiple constructors. The product sample in the distribution package (multiple_sliders_demo.html) clearly demonstrate this approach.

Below is the complete list of the configuration keys supported by the Tigra Slider Control. Unless otherwise specified all the parameters are required.

KeyDescriptionAccepted Values
b_vertical Specifies if the slider bar is vertical or horizontal.
Vertical slider bar has its minimum value in the lowest position, horizontal bar has its minimum value in the leftmost position.
true, false
b_watch If true the slider will continuously update the value in the input box during the slider movement, if false then the value will be saved when the slider is released. To optimize the browser resources utilization always set to false if the slider attached to hidden field. true, false
s_name Specifies the name or the ID of the input field to synchronize with. The input box must exist in the HTML document at the time of first change to the position of the slider.
If s_form parameter is defined then s_name must match the NAME attribute of the input box, otherwise it must match its ID attribute.
If the input element exists in the HTML document at the time of the slider initialization then its non empty value will be used as the initial setting for the slider.
string matching the name or ID of the input box
s_form Specifies the name or numeric index of the HTML form hosting the input box that the slider attaches to. This parameter is optional. If s_form is omitted the value of s_name must match the ID of the input box, otherwise it must match the NAME attribute. string matching the name of the form or its zero based numeric index
n_minValue Sets the lower boundary of the values range returned by the slider. This is the value the vertical slider will return in its lowest position and horizontal slider will return in its leftmost position. Negative numbers are accepted.
Any attempts to set the slider to the value lesser than n_minValue using the API calls will result in setting it to n_minValue, no error message will be generated.
number greater than n_maxValue
n_maxValue Sets the upper boundary of the values range returned by the slider. This is the value the vertical slider will return in its topmost position and horizontal slider will return in its rightmost position. Negative numbers are accepted.
Any attempts to set the slider to the value greater than n_maxValue using the API calls will result in setting it to n_maxValue, no error message will be generated.
If n_step is set then it is logical to have n_maxValue so n_maxValue - n_minValue is the multiple of n_step, otherwise the size of the last step will be different from n_step
number lesser than n_minValue
n_step Sets the discreteness of the values returned by the slider. This parameter is optional, if omitted the value will be calculated exactly based on the position of the slider, otherwise it will be rounded to the nearest step. The steps are counted from n_minValue (not from 0) so the result will be not necessarily the multiple of the n_step.
If both n_step and b_watch parameters are set then the slider will snap between the steps when moved, with b_watch set to false it will move smoothly and snap to the closest step location when released.
This parameter can be used to set the precision of the result i.e. setting step to 1 will return only integers, setting to 0.01 will round the result to 2 numbers after the decimal point (this assumes the n_minValue is the multiple of the n_step).
number multiple times lesser than n_maxValue - n_minValue
n_value Specifies initial value of the slider. The value will be applied if the slider can't find the input box at the initialization time (i.e. it is defined below in the HTML file) or the input box is blank.
This parameter is optional. If slider can't detect the initial value it will default to n_minValue.
If n_step is specified then value will be rounded to closest step.
number between n_maxValue and n_minValue
n_controlWidth The width of the control in pixels. Usually this equals the width of the background image of the slider (see s_imgControl below) in other cases the background image will be cropped or multiplied.
This is the size the control will take horizontally when positioned relatively in the container HTML element.
positive integer number
n_controlHeight The height of the control in pixels. Usually this equals the height of the background image of the slider (see s_imgControl below) in other cases the background image will be cropped or multiplied.
This is the size the control will take vertically when positioned relatively in the container HTML element.
positive integer number
n_sliderWidth The width of slider's handle in pixels. Usually this equals the width of the slider image (see s_imgSlider below) in other cases the slider image will be resized. positive integer number
n_sliderHeight The height of slider's handle in pixels. Usually this equals the height of the slider image (see s_imgSlider below) in other cases the slider image will be resized. positive integer number
n_pathLeft The horizontal offset in pixels between the left edge of the control and the left edge of the slider handle when it is in leftmost position (see the image below for clarification). Negative values are accepted. integer number
n_pathTop The vertical offset in pixels between the top edge of the control and the top edge of the slider handle when it is in topmost position (see the image below for clarification). Negative values are accepted. integer number
n_pathLength The length in pixels that the left corner of the slider handle can travel down if b_vertical is set to true or right if b_vertical is set to false (see the image below for clarification). positive integer number
s_imgControl The path of the background image of the slider. The path can be absolute or relative. When relative path is used it is resolved based on the location of the HTML document the slider is initialized in. string, path of existing image
s_imgSlider The path of the slider handle image of the control. The path can be absolute or relative. When relative path is used it is resolved based on the location of the HTML document the slider is initialized in. string, path of existing image
n_zIndex The z-index value applied to the slider handle. Usually 1 is acceptable setting but higher value may be needed if the slider is initialized in the upper layers of the document. positive integer number

The image below illustrates the layout settings of the Tigra Slider Control:

Some basic notes on the syntax of the structures:

Slider Control API

Note that although the techniques described in this section are pretty simple using the API is considered advanced topic and unlike other sections in this documentation it assumes at least basic understanding of JavaScript or/and OOP.

The internal methods and properties of the slider control can be accessed via the reference of the slider object. Each instance of the slider is represented by the object and created during the initialization. The reference can be obtained in one of two ways:

  1. reference returned by the constructor at the initialization time
  2. reference accessed via global array of the sliders by the numeric index after the initialization
<script language="JavaScript">
	var o_sliderRef1 = new slider(A_INIT, A_TPL); // method 1
	var o_sliderRef2 = A_SLIDERS[0];              // method 2
</script>

The number in the brackets is the zero based index of the slider on the page in order it was initialized.

Tigra Slider Control utilizes several methods, but probably the only one that is really usable as the API call is f_setValue. This method can be used to set the scroller to some value from outside. Below is the fragment of code from one of the samples included in the distribution package:

<input name="sliderValue1h" id="sliderValue1h" type="Text" onchange="A_SLIDERS[0].f_setValue(this.value)">

This code configures the input box to post the value to the attached slider if it was changed directly by typing in the edit area.

Tigra Slider Control has many internal properties including all the settings received from configuration structures (all have matching names) however most of them will stay unchanged after the initialization time, the only exception is n_value which contains current value. This parameter should not be used to set the value, use method f_setValue(..) instead.

The sample of the advanced use of the control's API is included in the distribution package (equalizer_demo.html)

Terms and Conditions

Tigra Slider Control is public domain i.e. FREE without any limitations.

Links and References