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.

  1. Include script tags pointing to the external JavaScript files.
  2. Place an image tag in the document where you wish your images to rotate.
  3. Set up the rotator's properties in an object literal.
  4. 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.

Back to top

  1. We have prepared a brief tutorial on Object Literals for those unfamiliar with the syntax.^
  2. When using the dw_getRandomImage function 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. ^