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 PRO v1.1 - Documentation

Table of Contents

Description

Tigra Slider Control PRO - is DHTML component for the websites that adds advanced vertical and horizontal trackbar capability to the HTML forms similarly to the controls widely used in desktop applications. The position of the handler is translated into the value from specified range and placed in existing input box of the HTML form. The slider is simple improvement that makes the interface more user friendly.

Features

Compatibility Table

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

PlatformBrowser
MS IENetscapeFirefox/MozillaOperaSafariAOL
Windows 95/98/ME/2000/XP4.x+6.x+0.9.x+7.x+n/a4+
Mac OS 8.6/95.x+6.x+1.1+7.x+1.3.1+n/a
KDE on Linux/FreeBSDn/a6.x+1.1+7.x+n/an/a

Files

The code of the Tigra Slider Control PRO 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
 
Layout
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. If slider is reversed (see b_reverse below) then positions are opposite.
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
b_reverse If set to true then reverses the slider -- vertical slider bar will have its minimum value in the upper position, horizontal bar will have its minimum value in the rightmost position. Logically the plus and minus buttons (see s_imgMinus*, s_imgPlus* below) switch their locations when slider is referred. And lastly the clipping of the progress bar (see s_imgBar below) is affected. This parameter is optional, defaults to false if not specified. true, false
Input
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
Values
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
Sizes and Timing
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. This parameter is not affected by reversing (see b_reverse above). 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. This parameter is not affected by reversing (see b_reverse above). 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
n_spacing The gap in pixels between the control's body and buttons, also the margin around whole control. positive integer number
n_repeatPeriod The period in milliseconds (1/1000th of the second) between increments or decrements while plus or minus button (respectively) is kept pressed. positive integer number
Images
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_imgControlActive The path of the background image of the slider while in use (handler is being dragged or button is being pressed). 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. This parameter is optional. The rollover effect will be disabled if this parameter is omitted. string, path of existing image
s_imgBar The path to the progress bar image that appears between background (see s_imgControl and s_imgControlActive above) and slider handle (see s_imgSlider below). This image is positioned at the same location as the background and clipped vertically (if slider is vertical) or horizontally (if slider is horizontal) between the side of the control with the minimum value and current location of the slider handle. This parameter is optional, if omitted the progress bar will not be displayed. 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
s_imgMinus The path to the minus (decrement) button image in its default state. This parameter is optional, if omitted the plus button will not be displayed and other related parameters (see next 3 below) will be ignored. 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_imgMinusDisabled The path to the minus (decrement) button image in its disabled state (when current value is at allowed minimum). This parameter is optional. 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_imgMinusHover The path to the minus (decrement) button image in its rollover state (when mouse is placed over the button). This parameter is optional. 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_imgMinusDown The path to the minus (decrement) button image in its active state (when mouse is pressed on the button). This parameter is optional. 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_imgPlus The path to the plus (increment) button image in its default state. This parameter is optional, if omitted the plus button will not be displayed and other related parameters (see next 3 below) will be ignored. 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_imgPlusDisabled The path to the plus (increment) button image in its disabled state (when current value is at allowed maximum). This parameter is optional. 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_imgPlusHover The path to the plus (increment) button image in its rollover state (when mouse is placed over the button). This parameter is optional. 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_imgPlusDown The path to the plus (increment) button image in its active state (when mouse is pressed on the button). This parameter is optional. 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
Event Handlers
h_onButton Custom event handler called when slider button is pressed or button related command is fired. The handler receives two parameters: button name ('Minus' or 'Plus') and event name ('out' for moving the mouse out of the button, 'over' for moving the mouse over the button, 'down' for pressing the button, and 'up' for releasing the button). Inside the event handler this refers to the slider control object. The handler must return true unless default (internal) handler must be disabled. This parameter is optional. reference (name without brackets, quotes or apostrophes) of the previously defined custom function
h_onChange Custom event handler called when the value is saved in the input box. The handler receives one parameter: the value that is being saved. Inside the event handler this refers to the slider control object. The handler must return true unless default (internal) handler must be disabled. This parameter is optional. reference (name without brackets, quotes or apostrophes) of the previously defined custom function
h_onMove Custom event handler called each time the slider handle is moved. The handler receives one parameter: the value represented by current position of the slider. Inside the event handler this refers to the slider control object. The handler must return true unless default (internal) handler must be disabled. This parameter is optional. reference (name without brackets, quotes or apostrophes) of the previously defined custom function

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

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 PRO 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 PRO 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

Regular License

One Regular (single domain) Tigra Slider Control PRO script license gives the right to use one copy of the script (file: slider.js) within single domain boundaries.

Demo of Licensing Cases:
First Site URL Second Site URL Number of Licenses Required
http://www.domain.com/site_1/ http://www.domain.com/site_2/ one
http://www.domain1.com/ http://www.domain2.com/ two
http://subdomain1.domain.com/ http://subdomain2.domain.com/ two

Developer License

Developer (royalty free) license gives the right to include unlimited number of Tigra Slider Control PRO instances in the products of license owner.

Discounts

We offer 50% discount for the script starting from second license. To take advantage of this discount use the link sent with every order confirmation message.
Same discount initially applies to educational and religious organizations.

Usage

As owner of the Tigra Slider Control PRO license You are allowed to configure the script in any possible way for use in Internet (public), Intranet (corporate) or offline application, however You are strictly NOT allowed (unless specifically authorized by SoftComplex.com) to:

Technical Support

You are entitled to free product upgrades and technical support for at least one year from the date of purchase. Technical support includes answers to script related questions via e-mail and/or Internet instant messaging services. Full slider customization services are provided on customer's request at additional charge. Free setup support does not include product API/events programming services.

Violations of Terms and Conditions

Should you violate these Terms and Conditions or any other rights of SoftComplex Inc., SoftComplex Inc. reserves the right to pursue any and all legal and equitable remedies against you without limitation.

Standard disclaimer applies see http://www.softcomplex.com/site_agreement.html for full text.

Links and References