/*** (C)Scripterlative.com
S m a r t R o l l.
Pre-settable Latching Rollover Buttons with 2 or 3-State Operation, Pre-settable buttons and
Optional Captioning.
Info: http://scripterlative.com
These instructions may be removed but not the above text.
Please notify any suspected errors in this text or code, however minor.
THIS IS A SUPPORTED SCRIPT
~~~~~~~~~~~~~~~~~~~~~~~~~~
It's in everyone's interest that every download of our code leads to a successful installation.
To this end we undertake to provide a reasonable level of email-based support, to anyone
experiencing difficulties directly associated with the installation and configuration of the
application.
Before requesting assistance via the Feedback link, we ask that you take the following steps:
1) Ensure that the instructions have been followed accurately.
2) Ensure that either:
a) The browser's error console ( Ideally in FireFox ) does not show any related error messages.
b) You notify us of any error messages that you cannot interpret.
3) Validate your document's markup at: http://validator.w3.org or any equivalent site.
4) Provide a URL to a test document that demonstrates the problem.
Installation
~~~~~~~~~~~~
These instructions assume that an HTML document has been prepared, containing suitable image-based
navigation buttons surrounded by hyperlinks.
Each image placeholder must have a unique NAME or ID attribute.
Save this file or text as smartroll.js and copy it to a suitable folder relating to your web pages.
Within the section of all documents that will use the script, at a point below the last
image in the document, insert the following:
(If smartroll.js resides in a different folder, include the relative path)
Configuration
~~~~~~~~~~~~~
For each button group to be created, all that is required is a single call to the
function: SmartRoll.over, passing the required parameters.
Clear examples are given below.
The first parameter is the name given to the group of buttons. This can be any unique name.
All subsequent parameters are passed in groups of either two or three, depending upon whether
tristate buttons are to be created. In each parameter group, the parameters are as follows:
First parameter - the NAME or ID attribute of the first button's image placeholder or ![]()
tag.
Second parameter - the file name (and path if needed) of the 'hover' image file.
Third parameter - (If required) the file name (and path if needed) of the 'active' image file.
Note: The script detects the default image for each button, which is loaded by its ![]()
tag
in the usual way.
Example 1. Create a group of five latching rollover buttons. The group is named 'buttonset1', the
image placeholders are named 'btn1' - 'btn5', the images to be used reside in the folder
'/images', the hovered-state images are named 'hov1.gif' - 'hov5.gif':
Example 2. Create another menu as above, but using tri-state buttons. The active-state images
are named 'act1.gif' - 'act5.gif':
Note: In dual-state operation you will notice that when a button is latched, hovering another
button returns the latched button temporarily to its default state. If you prefer this not to
happen, configure the group for tri-state operation specifying the same image for 'hover' and
'active'.
Pre-Setting A Button
~~~~~~~~~~~~~~~~~~~~
On page load, there are two ways to preset a button from each group into its active state.
1) SmartRoll.setButton( placeHolder ), where 'placeHolder' is the Name or ID attribute of the image
placeholder of the relevant button:
SmartRoll.setButton( 'btn3' );
NOTE. This function must be called after the creation of the button group to which it applies.
To set a button from another frame, pass a reference to the target frame as a second parameter:
2) In the target URL, pass the parameter: SmartRoll=placeHolder, where placeHolder means the
same as above.
Example. On a literary website that displays the same button menu on each page, a hyperlink
on the home page navigates to the fiction page, on which the 'fiction' button is to be set to
its active state.
....
To set more than one button (in different groups) in this way, repeat the parameter with
the required values: href='fiction.htm?SmartRoll=fictBtn&SmartRoll=sciFi'
Note: If you test this facility locally in the address bar, the URL should start 'file:///c:'
rather than 'c:/', at least for Internet Explorer.
Note: Method 1 overrides method 2.
Making buttons 'de-latchable'
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Any set of buttons can be configured such that if a latched button is clicked, it reverts to its
default state. This can be useful when using rollovers to control toggle operations, for instance
showing and hiding one of a group of elements. To enable this functionality, in the function call
simply append '|UNLATCH' to the name of the relevant button group.
SmartRoll.over
(
'buttonset1|UNLATCH', .......
};
Emulating 'Radio' Buttons
~~~~~~~~~~~~~~~~~~~~~~~~~
To create the effect where a rollover button changes only when clicked, use tristate mode
and specify the same image for hover as the corresponding default image.
Captions
~~~~~~~~
The optional captioning facility is initialised separately, via a call to SmartRoll.setCaptions.
The parameters are as follows:
Parameter 1: The NAME of the button group.
Parameter 2: The ID of the element that will display the caption text (Usually a DIV or SPAN).
Parameter 3: The default caption text. To use the element's initial content, specify this as "".
Subsequent parameters consist of Image identifier/Caption pairs, one for each button to be captioned.
Example 3. The button set created in Example 2 is to be used on a model shop's website. It will
be assigned captions that are to appear in a span whose ID is 'captionLine'.
SmartRoll.setCaptions
(
'myButtons', 'captionLine', 'Welcome to Crashwell Models',
'btn1', 'Powered aircraft, ready-to-fly and in kit form.',
'btn2', 'A comprehensive range of glow and diesel aero engines.',
'btn3', 'Radio sets and accessories from the world\'s leading manufacturers.',
'btn4', 'Field Boxes, Electric Starters, Starter Batteries, Electric Fuel Pumps etc',
'btn5', 'Our new marine section has an exciting collection of water-borne models'
);
NOTES
~~~~~
1) For each captioned button set, the call to SmartRoll.setCaptions must be made after the
corresponding call to SmartRoll.over.
2) If you wish to use apostrophes within caption text, precede them with a backslash: \'
3) Multiple button sets may share the same caption element. When doing this, it may be
better to specify the default caption text as "" for all sets.
Troubleshooting
~~~~~~~~~~~~~~~
As always, ensure that the JavaScript console displays no error messages pertinent to your pages.
The encapsulated construction of this script, removes all risk of possible conflict with variables
from any other scripts in the document.
The most likely cause of trouble will be syntax errors in the function parameters.
Ensure that the example syntax has been followed exactly. It may be advisable to configure for just
two or three buttons initially.
Mouse Events
~~~~~~~~~~~~
The mouse event handlers generated by this script, will be appended to any created by
previously-loaded scripts or embedded statements. For this reason, try to load this script after
any other scripts that are known to use mouse events.
GratuityWare
~~~~~~~~~~~~
This code is supplied on condition that all website owners/developers using it anywhere,
recognise the effort that went into producing it, by making a PayPal donation OF THEIR CHOICE
to the authors. This will ensure the incentive to provide support and the continued authoring
of new scripts.
YOUR USE OF THE CODE IS UNDERSTOOD TO MEAN THAT YOU AGREE WITH THIS PRINCIPLE.
You may donate at www.scripterlative.com, stating the URL to which the donation applies.
*** DO NOT EDIT BELOW THIS LINE ***/
var SmartRoll=
{
/*** Free Download with instructions: http://scripterlative.com?smartroll ***/
imgArray:[], bon:0xf&0, logged:0,
iHover:function(name)
{
var e=this.getElem(name), obj, objArray;
if( e )
{
obj=e.elem; objArray=e.arr;
if(!obj.locked)
{
if( !obj.superElem.triState )
for( var i in objArray )
if( objArray[i] != obj && objArray[i].locked)
objArray[i].holder.src = objArray[i].defImg.src;
obj.holder.src = obj.overImg.src;
}
}
if( obj.superElem.captionHolder && obj.caption )
obj.superElem.captionHolder.childNodes[0].data = obj.caption;
},
iUnHover:function(name)
{
var e=this.getElem(name), obj, objArray;
if( e )
{
obj=e.elem; objArray=e.arr;
if( !obj.locked )
{
if( !obj.superElem.triState )
for( var i in objArray )
if( objArray[i] != obj && objArray[i].locked)
objArray[i].holder.src = objArray[i].overImg.src;
obj.holder.src = obj.defImg.src;
}
}
if( obj.superElem.captionHolder && obj.caption )
obj.superElem.captionHolder.childNodes[0].data = obj.superElem.defCaption;
},
iSelect:function(name)
{
var e=this.getElem(name), obj, objArray;
if( e )
{
obj=e.elem; objArray=e.arr;
obj.locked = obj.superElem.unLatch ? !obj.locked : true;
for( var i in objArray )
if( objArray[i] != obj)
{
objArray[i].locked = false;
objArray[i].holder.src = objArray[i].defImg.src;
}
obj.holder.src = obj.locked ? (obj.superElem.triState ? obj.activeImg.src : obj.overImg.src) : obj.defImg.src;
}
},
over:function()
{
if(document.images)
{
var eHandler = null,
objName = arguments[0].split('|')[0],
di = document.images,
imgObj = this.imgArray[ objName ] = {},
imageData = null, step = 2, img = null, len = 0;
imgObj.objectName = objName,
imgObj.triState = (arguments.length > 3 && di[arguments[4]]) || arguments.length==4,
step = imgObj.triState ? 3 : 2,
imgObj.unLatch=/\|unlatch$/i.test(arguments[0]),
imgObj.data = [];this.cont();
len = this.bon ? arguments.length : 0;
for(var i=1; i