Crossfade slideshow reference manual

Description & features

This JavaScript mini library purpose is to allow easy adding of a slideshow feature to a web page. It’s enough to fill an array with pictures and call two methods.

The pictures of the slideshow cross fade over each other in predefined time intervals.
Each picture can have its own region map defined.
Any picture of the array can be selected to start the slideshow with or the slideshow can start with a randomly selected picture from a subset of the array.
The slideshow can be stopped and rerun by code on the page (for example in events)
Any image, even not listed in the array, can be shown in the area of the slideshow using a simple function

Public variables

Pic

This array variable must be filled up with the images and their associated properties of the slideshow.
Every member of the array is a three member array of these parts:
- The image address
- The image map file (if any is defined)
- Flag to indicate if the cover can be randomly selected to be shown at the moment of page load (can be empty)
Example:
Pic[0] = ['http://www.mysite.com/img01.jpg','#image1map',true];
Pic[1] = ['http://www. mysite.com/img02.jpg ','# image1map',true];
Pic[2] = ['http://www. yoursite.com/funny.jpg','# image2map',false];
Pic[3] = ['http://www. othersite.com/imges/cool.png', '',false];
This variable must be initialized in the <HEAD> section of the page using the script (see Usage chapter). Any later changes in the array will be ignored unless function picRefresh is called.

slideShowSpeed

Default value: 7000
Valid values: integer grater then zero
Sets the speed, the time after which the image starts to change, of the slideshow in milliseconds.

crossFadeDuration

Default value: 3000
Valid values: integer grater then zero (internally rounded up to be dividable by 20)
Sets the duration (in milliseconds) of the images cross fade process. The precession granularity is 20 ms, meaning setting 1321 will take 1340ms.

startOpacityDegree

Default value: 10
Valid values: integer in the range <0, 100>
Base opacity degree to start the image to fade in from.
0..absolutely transparent = inivisible;100.. solid = no cross fade, immediate pop-up

mapSwapOpacityDegree

Default value: 10
Valid values: integer in the range <0, 100>
The opacity degree, when the map of the image will become active (until that the image map of the previous image is active; could be the same of course).
0-startOpacityDegreeimmediately;100..only when the image is fully shown

Other variables are defined in the library. Their usage outside the library is not advised tough as it my compromise the correct behavior of the functions.

Public procedures

function writeSlideShowCode

Paremeters:

slideshowWidth – the width of the slideshow container (implied in px). Set it to accommodate the largest image within the slideshow.
slideshowHeight – the height of the slideshow container (implied in px). Set it to accommodate the largest image within the slideshow
fadebgcolor (optional) – the background of the images; it only has meaning transparent or different size images

The function's return value - in case of DOM supporting browsers - is the object of slide show it created. It's useful to set up some additonal object properties for example.

This function must be called in the <BODY> section of the page at the place where the slideshow is to be displayed.

function initSlideShow

Paremeters:

in_StartImage – the image number of the Pic array to be used as the first appearing image. If set to -1 a random image is used (from the subset of the allowed ones)
in_RunSlideShow – flag, whether the slideshow should start automatically

This function must be called at least once for the slideshow to work correctly. It is advisable to call it in the onLoad event of the page.

function runSlideShow

This function is to manually start the slideshow, for example as a reaction to mouse movement over some region or mouse click on some element of the page.

The slideshow continues from the image currently showing, if it is a member of the array. Otherwise the slideshow continues with the image following the last one shown from the array.

The functions purpose is opposite of the stopSlideShow’s one.

function stopSlideShow

This function stops the slideshow, for example as a reaction to mouse movement over some region or mouse click on some element of the page.

The slideshow stops and the active image is made fully opaque if it’s not already.

The functions purpose is opposite of the runSlideShow’s one.

function showImage

Paremeters:

in_ImageSrc – the address of the image to be shown
in_ImageMap – the map that covers the image; can be empty

This functions shows the image specified in parameters covered by attached map (if supplied). The slideshow is stopped by this function. If the image is a member of the Pic array once the slideshow is restarted (by the function runSlideShow) it continues from the next image in the array, otherwise from the image following the last shown from the array.

function showImageByIndex

Paremeters:

in_ImageIndex

This function shows the image from the Pic array identified by the parameter. The image is made fully opaque and the slideshow is stopped. If it’s rerun later on (using the function runSlideShow) it continues with the image following the one shown by this function.

function picRefresh

This function has to be called if any changes made in the Pic array after the call of initSlideShow are to be registered. If the slideshow is active at the moment of refresh it's stopped and restarted after the refresh. The restart of the slideshow shows the first image in the Pic array.

There are other functions in the library with names starting with “_”. They are not intended to be called from outside the library.

Usage

Place the following code in the <HEAD> section of the page:
<script type="text/javascript" language="JavaScript" src="Dim8_crfdsldeshow.js"></script>
Fill the Pic array in the <HEAD> section of the page. Something like this:
<script type="text/javascript" language="JavaScript">
Pic[0] = ['http://www.mysite.com/img01.jpg','#image1map',true];
Pic[1] = ['http://www. mysite.com/img02.jpg ','# image1map',true];
Pic[2] = ['http://www. yoursite.com/funny.jpg','# image2map',false];
Pic[3] = ['http://www. othersite.com/imges/cool.png', '',false];
</script>
Call the writeSlideShowCode function at the <BODY> section of the page at the place, where you want the slideshow to appear.
<p><script type="text/javascript" language="JavaScript">writeSlideShowCode(620,380,"black");</script></p>
Call the initSlideShow function; the advised place to do it is in the onLoad event of the page.
<body ONLOAD="initSlideShow(-1,true)">
(optional) You can stop or run the slideshow or change the image displayed depending on the events on the page calling the appropriate functions

Unfortunately the script does not support more then one slideshow per page. To have more frames or iframes have to be used.

Compatibility

Compatible

Internet Explorer 5 +

Firefox
Mozilla
Opera 9+
Netscape 6+
Safari
Konqueror

Limited compatibility

(no cross fade, direct change of images)

Internet Explorer 4
Opera prior to version 9

Tested on

Firefox 2.0
Internet Explorer 7.0
Mozilla 1.7
Opera 9.10
Opera 8.54

Incompatible

Internet Explorer prior to version 4
Netscape Navigator up to version 4 (4 included)

The compatibility with other browsers depend whether they support DOM and opacity.

Version history

1.0	26.I.2007	The first version released
1.1	01.II.2007	fadebgcolor in writeSlideShowCode can be omitted now, no background then. The image is changed only when URL differs (better for IE behavior).
1.2	15.II.2007	writeSlideShowCode function now returns a reference to the object it created (in DOM browser), so its various properties can be set.

Credits

The library was created by 8 Dimensions. Go to www.8dimensions.com to see more.

Big thanks goes to CodeLifter.com whose FadeIn_1_5 script was a big inspiration and source of ideas.