Rotate Images Documentation
Generally, the best starting point for setting up the Rotate Images code is to select an example from the download file that most closely resembles the implementation you desire. Examples in the download file are designed to make it as easy as possible for you to locate the code components required.
Instructions
The following list outlines the simple steps for implementing the code. Details on each step are available below.
- Include script tags pointing to the external JavaScript files.
- Place an image tag in the document where you wish your images to rotate.
- Set up the rotator's properties in an object literal.
- Initialize the code.
Script Tags
Place script tags for the external JavaScript files in the head of your document:
<script src="js/dw_event.js" type="text/javascript"></script> <script src="js/dw_rotator.js" type="text/javascript"></script>
Some implementations (such as Random Rotation) require an additional JavaScript file: dw_rotator_aux.js. The example documents will inform you of that and demo's in the download file will include all required files. ^
Image Tag
Place an image tag in the document where you wish your images to rotate. Include the id attribute in the tag and assign a unique id. Assign the first image to appear there to the src attibute. For example:
<!-- Images rotate here. --> <img id="r1" src="images/smile.gif" alt="" />
Other image tag attributes, including height and width, are optional. See information on using images of varying dimensions in the rotation.
If your image is to be linked you specify the URL in the link's href attribute:
<!-- Images rotate here. --> <a href="index.html"><img id="rotate_img" src="images/swans.gif" alt="" /></a>
A blue border will appear around linked images unless you indicate otherwise, either in the border attribute of the image tag (border="0") or in the style sheet. If you are using a strict doctype and want your document to validate place the following in the style sheet:
a img { border:none; }
Even if each image is to navigate to a different URL onclick, you set up the initial image this way with the first URL or other action to be taken on click. See more information for setup of linked images with separate destination URLs by viewing the Linked, Distinct URL's example on the Demo's Page.
Note: Random Rotation requires a different setup if the first image is to be selected at random from your list of images. ^
Rotator Properties
Specify what images you want to include as well as other properties in an object literal[1] as demonstrated here:
var rotator1 = {
path: 'images/', // path to your images
id: 'r1', // id assigned in image tag
bTrans: true, // transition filter for IE Win
images: ["smile.gif", "grim.gif", "frown.gif", "bomb.gif"]
}
There are several other properties that you can control with specifications in the object literal, such as rate of rotation. See below for more information. Examples listed in the right column demonstrate the various features supported by the code. ^
Initialize
The code is initialized with a call to dw_Rotator.setup:
function initRotator() {
// pass name of variable containing rotator properties
dw_Rotator.setup(rotator1);
}
addLoadEvent(initRotator); // Simon Willison's onload function
The variable containing the rotator properties and the function to initialize the rotator can be included in a script segment or an external JavaScript file. ^
Multiple Instances
You can add as many instances of rotating image blocks as you like with this code. Since some users may be annoyed by all this activity, it might be advisable to include controls for stopping and perhaps restarting the rotation. Instructions are included below for setting up stop/restart controls.
An example on the Demo's Page demonstrates and provides more information about the process of setting up multiple instances of rotating images including whatever features the code supports.
Setting up the Stop/Restart Links
The code to set up the stop/restart links is contained in the dw_rotator_aux.js file. Include a script tag for it in the head of the document with the other external JavaScript files required by the code. (The download file contains an example implementing the stop/restart controls.)
Include the links (text or images of your choice) in an element with a rotator_controls class attached. The links themselves should also have classes attached: stop and start:
<p class="rotator_controls"> <a class="stop" href="#">Stop Rotation</a> | <a class="start" href="#">Restart Rotation</a> </p>
Include a call to the dw_Rotator.addControls function in the head of the document:
addLoadEvent(initRotators); addLoadEvent(dw_Rotator.addControls);
Rotator Properties
The following is an example object literal for rotator properties listing them all:
var rotator = {
path: 'images/', // path to images
id: 'rotate_img', // // id assigned in image tag
speed: 3000, // delay (milliseconds) between image swaps (default: 4500)
bTrans: true, // IE win transition filter
bMouse: true, // pause/resume onmouseover/out
bRand: true, // random rotation
images: ["smile.gif", "grim.gif", "frown.gif", "bomb.gif"],
// URLs or other actions onclick of images
actions: ["http://www.dyn-web.com/code/rotate_images/",
"http://www.dyn-web.com",
"just_rotate.php",
"http://www.dyn-web.com/business/terms.php"],
// title attribute content
title: ["That's a nice smile!", "Looking pretty grim!",
"Why such a sad face?", "Oh oh, look out!"],
// alt attribute content
alt: ["smile", "grim face",
"sad face", "bomb"],
captionId: 'img_caption', // id of element where captions will be displayed
// caption content
captions: ["That's a nice smile!", "Looking pretty grim!",
"Why such a sad face?", "Oh oh, look out!"]
}
Notice that images, actions, title, alt, and captions are all array literals and would generally[2] be expected to have the same number of elements (they are parallel arrays).
About Image Size Variation
If you place the first image in your page source and include height and width attributes in the image tag, subsequent images not that size will be resized to fit those height/width specifications. If you do not include height and width attributes, current browsers will display the images at their actual sizes and reflow page content as needed. You can set width and height on a containing element large enough to accomodate the largest image to be rotated in to avoid document reflow.
If your images vary in size, it is suggested that you turn off the transition filter option (bTrans in rotator properties) since it may be a less than attractive effect under these circumstances.
- We have prepared a brief tutorial on Object Literals for those unfamiliar with the syntax.^
- When using the
dw_getRandomImagefunction to display the first image selected at random from the list of images, if they are all to navigate to the same URL, have the same title etc. then there would only be one entry in the corresponding array in the rotator properties variable. ^