ColdFusion in Context: Slide Shows

If your presentation flips to the next screen before the first screen has been visible for the desired length of time, or worse yet hasn't finished loading at all, your users will get frustrated. Perhaps you have a large graphic to display, or perhaps you have to generate a complex page based on data just received from the user. This tip, disguised as a slide show, demonstrates one way to be sure that your presentation doesn't leave its viewers behind.

One basic problem with using large images in slide shows is that you can't trust or use the timing events associated with images. The "completed" and "onLoad" events claim that the image has finished loading when it has barely begun to load. Therefore, your presentation assumes the user has seen the image long enough and begins to load the next image before the previous one has even reached the screen. Worse yet, changing the image source of an image already displayed, a common technique to run a slide show, generates an onLoad event by itself and can lock up a Netscape browser if you're trapping the image onLoad event to determine if an image has finished loading.

Therefore, although you've seen many good-looking slide shows that display small images on a single page, this isn't a robust method to use if you suspect that your images might take nearly as long to load as the time you have planned to pause between images. This tip uses a different event to detect that the page is ready: the body onLoad event. An added benefit of using this event instead of timing images directly is that you can flip and time entire pages, not just images. Let's flip pages first.

Build the Frameset

Put this code in tour.cfm. It will reserve the first 65 pixels in height for the controls and description. The remainder will be available for the page to be flipped. Set the border attribute to zero to keep Netscape from displaying borders. Set frameborder to "no" to do the same for IE. Turn scrolling off for the top frame; this looks really nice. If you know your display page will fit in the window, turn off scrolling for the second frame as well, to provide the illusion that the presentation is handled by a single page. 

</script>
</head>
<frameset rows="65, *" name="one">
<frame src="tour2.cfm" name="two" border="0" 
frameborder="no" scrolling="no">
<frame src="tour3.cfm" name="three" border="0" 
frameborder="no">
</frameset>
<body>
.
</body>

Work with the Description Page

Put this code in tour3.cfm. After this description page loads, it waits a moment for the control page to settle down, then changes a form value in the control page to tell it that this page has loaded. The description page describes how to use the controls. 

<body onLoad=
"javascript:setTimeout('parent.two.document.playback.ok.value=1',1000);">
<hr><div align="center">If you resize your window, press [>] to resume.
Change speed with [--] or [++] if needed.  
The presentation runs automatically.</div><hr>

Initialize

Put this code in tour2.cfm. To make the presentation roll between the last item and the first, you need to know the number of items in the list (Nr). The slide list will compute Nr. To work with a specific item, you need to know its position in the list ("Show" this item). For each item, it is useful to be able to specify its Source, its Caption, and the relative amount of time the item is to be displayed (Pause). Setting the Gear (to be multiplied by the Pause for any given item), allows one to make an overall adjustment to the time that all items are displayed. The direction of play can be backward (negative), forward, (positive), or no direction at all (zero). It is defined (as zero) so it will exist when the functions using it are initially defined. A value for the Waiter timer (described later) is provided so it will exist if you try to stop it before it's first used. 

<script language="javascript">
// Initialization...
Show = 0; // array position of current item
Nr = 0; // will become number of items
Source = new Array;
Caption = new Array;
Pause = new Array;
Gear = 500; // user-changeable multiplier for pause
By = 0; // direction of play
Waiter = 0; // timer to wait with

Define the Slides

To make it easy to change the slide list, it is composed of blocks that increment the item number and ultimately the number of items. Put this code in tour2.cfm. 

// Slides...
// To add/change/rearrange/remove slides,
// just add/change/rearrange/remove blocks below.

Nr = Nr + 1;
Source[Nr] = "../slide/one.cfm";
Caption[Nr] = "First.";
Pause[Nr] = 15;

Nr = Nr + 1;
Source[Nr] = "../slide/two.cfm";
Caption[Nr] = "Second.";
Pause[Nr] = 5;

Nr = Nr + 1;
Source[Nr] = "../slide/three.cfm";
Caption[Nr] = "Third.";
Pause[Nr] = 10;

Set Control Code

Put this code in tour2.cfm. It's easier to understand it if you work from the bottom. It waits 5 seconds (5000 milliseconds), then tries to advance to the next item. It doesn't succeed in advancing to the next item until the description item finishes loading and sets a form variable as previously described. It keeps trying every tenth of a second until this occurs. See playItems().

When it's ok to change items, it considers the direction in which it should change, resets the form variable to indicate that the desired page hasn't loaded, and then loads the page. See changeItem().

After initiating the page load, the code waits for the item's pause length times the Gear size, then tries to advance to the next page. See loadPage().

The user will increase and decrease the gear size by changing it with a Shift value. See changeGear().

The native javascript setTimeout() function gives the code an odd quality at times. This function is not a "wait" statement. It doesn't stop the current program flow. Instead, it spawns a new process when the timeout is reached. Therefore, if any process manages to initiate the setTimeout() function before it's done, multiple copies of the timer would be spawned. If the Auto button started the timer itself, pressing Auto multiple times would cause multiple timers to run simultaneously; the user would have to press the Manual button several times to stop all of them. To keep this from happening, when the user presses the Auto button, the code deliberately stops the current copy of the timer before starting a new copy and advancing to the next item. For this reason, pressing the Manual button once stops the timer. See doRun() and stopItems(). 

// Controls...

function loadPage() {
  parent.three.document.location = Source[Show];
}

function changeItem(Direction) {
  Show = Show+Direction;
  if (Show < 1) Show = Nr;
  if (Show == Nr + 1) Show = 1;
  document.playback.ok.value = 0;
  loadPage();
  document.playback.Docent.value = Caption[Show];
}

function stopItems() {
  clearTimeout(Waiter);
  clearTimeout(Runner);
  clearTimeout(Waiter);
}

function playItems(By) {
  if (document.playback.ok.value == 1) {
    changeItem(By);
    Runner = setTimeout('playItems(1)',Gear*Pause[Show]);
    return true;
  }
  else {
    Waiter = setTimeout('playItems(1)',100);
  }
}

function doRun() {
  stopItems();
  playItems(1);
}

function changeGear(Shift) {
  Gear = Gear+Shift;
  if (Gear < 100) Gear = 100;
  if (Gear > 2800) Gear = 2800;
}

// Begin in Play mode
Runner = setTimeout('playItems(1)',5000);
</script>

Create Controls

Put this code in tour2.cfm. The mini-style sheet keeps the home link from being underlined. You can easily remove it, or you can add a small image as a hint to click on "Home". In order to easily get a background color for the controls, encase them in a table. To avoid unwanted gaps between supporting and main buttons, be especially careful to leave no space or line break between the tags of the Auto button group and between the tags of the Manual button group. On the other hand, non-breaking spaces are handy to separate the two groups. The -- button slows the presentation by increasing the size of the gear; the ++ decreases the gear to make the presentation flip faster. The less-than sign requests a backward move; the greater-than sign requests a forward one.

Because there is no caption for the control description page, a non-breaking space serves as the initial caption. Wrap in a "virtual" rather than in a "physical" fashion; because, line breaks in the caption text don't need to be preserved. 

<style>
a {text-decoration:none;color:black;font-weight:bold;}
a:hover {color:green;}
</style>
<table align="center" cellpadding="0">
<tr>
<form name="playback">
<td bgcolor="#00AACC">
<a href="../public/home.cfm">Home</a>
<input type="button" value="- -" 
onClick='changeGear(+50)';><input type="button" 
value="Auto" onClick='doRun();'><input 
type="button" value="++" onClick='changeGear(-70)';>
&nbsp;&nbsp;
<input type="button" value="<" 
onClick='changeItem(-1);'><input type="button" 
value="Manual" onClick='stopItems();'><input 
type="button" value=">" onClick='changeItem(1);'>
</td>
<input type="hidden" name="ok" value="0">
<td>
<textarea name="Docent" wrap="virtual" cols="60" rows="2">
&nbsp;</textarea>
</td>
</form>
</tr>
</td></tr></table>

Build Tour Pages

EVERY tour page must contain this magic code. Once the page loads, then it pauses for a short period (to let the control page settle down) and then changes a field in the control page to 1 to tell it that this page is fully displayed. 

<body onLoad=
"javascript:setTimeout('parent.two.document.playback.ok.value=1',500);">

Let this code be one.cfm. It's a sample for the demonstration... 

<body onLoad=
"javascript:setTimeout('parent.two.document.playback.ok.value=1',500);">
This is page one.

Let this code be two.cfm... 

<body onLoad=
"javascript:setTimeout('parent.two.document.playback.ok.value=1',500);">
<hr>
This is page two.
<hr>

Let this code be three.cfm... 

<body onLoad=
"javascript:setTimeout('parent.two.document.playback.ok.value=1',500);">
This is page 3.
Here is a unique identifier generated by ColdFusion:
<cfoutput>#createUUID()#</cfoutput>.

Make an Image Slide Show from the Page Tour

The page tour works now on a Web server; browse tour.cfm to try it out. However, suppose you really wanted to flip only images. A few small changes to what we've done so far will make this possible. To make an slide show from this tour, copy tour.cfm to slide.htm; tour2.cfm to slide2.htm, and tour3.cfm to slide3.htm. The changes follow:

In slide.htm, replace "tour2.cfm" with "slide2.htm" and "tour3.cfm" with "slide3.htm".

In slide2.htm, replace function loadPage() with this code. Instead of displaying an existing page, it writes a page "on the fly" that consists of a body tag and an image tag. The body tag contains the magic code you manually added to the beginning of the pages you displayed during the tour. The image tag contains the appropriate source for the image from your item list. 

function loadPage() {
  Content = 
"<body onLoad=javascript:setTimeout('parent.two.document.playback.ok.value=1',500);>";
  Content = Content + "<img src=" + Source[Show] + ">";
  parent.three.document.write(Content);
  parent.three.document.close();
}

Now fix the item list so it contains references to images instead of to pages. You can name them anything and put them anywhere. Here's a sample: 

Nr = Nr + 1;
Source[Nr] = "../slide/one.gif";
Caption[Nr] = "First.";
Pause[Nr] = 15;

Nr = Nr + 1;
Source[Nr] = "../slide/two.gif";
Caption[Nr] = "Second.";
Pause[Nr] = 5;

Nr = Nr + 1;
Source[Nr] = "../slide/three.gif";
Caption[Nr] = "Third.";
Pause[Nr] = 10;

Don't do anything to slide3.htm; it's fine as it stands. In fact, you're done. Browse slide.htm to see this work. At this point, the slide show doesn't even need a Web server!

Lessons and Projects

If you "snapshot" a page from your website and try to use it in a slide show, you'll wind up with an image half the size of a floppy disk: about 500K. A user viewing your show using a dialup service may find that it takes more than two minutes to load such a page. Although the code in this tip will actually wait the two minutes and then provide the desired pause before moving to the next slide, you and your user will be better served if you create a page tour instead. It takes dramatically less bandwidth to tell the browser how to draw a screen than it does to send it the image of a screen. This tip gives you a choice of techniques.

Try creating more complex pages with the document.write function used in the slide show. If the page you're "replacing" ends in .cfm, you may be able to code some ColdFusion functions and tags into the replacement page "on the fly". Tell us what you've learned. Apply these techniques in good health. =Marty=