JavaScript Tip of the Week for November 18, 1996: A JavaScript Tour | 3 | WebReference

JavaScript Tip of the Week for November 18, 1996: A JavaScript Tour | 3

JavaScript Tip of the Weekfor November 18, 1996: A JavaScript Tour

The JTotW tour was "pretty cool", but I'm sure all you more artistic scripters out there can customize it to do a better job in presenting your sites. What I like about the tour is that it takes care of a lot of frequently asked questions about a site right off the bat. I guess you could think of it as an automated interactive FAQ. It may save you a lot of e-mail (answering those questions) and it will most certainly be a welcome sight to all the newbies out there.
Learn How It Works  
Make It Work for Me

Let's Define Some Variables

All that interactive talk is great, but if it's a pain to put together then what's the point? For the most part, this one's a no brainer. First on the list of things to do is define a few variables:
    var cur = 0;
    var curStop = 0;                 <-- defines the current tour stop
    var lastMus = '';                <-- defines last music played
    var tourStops = new makeArray(); <-- array containing the tour objects
    var musicEnabled = true;         <-- boolean determining whether to play music
    var lastStop = 'index.html';     <-- page that user will be brought to
                                         at the end of tour
These variables simply lay out a foundation for the tour. The cur variable is just a temporary variable that will be used in constructing the array objects.
Creating the Tour Object

The tour object is very basic; it contains only three properties. The first is the URL of the page that will be displayed with the current tour stop; referred to as url. This is always relative to the location of the document. The second property, desc, contains the text and graphics that will explain what the user is seeing on the page. This is where you can explain how the page works. The third and final property, mult, contains the file name of the MIDI or sound file that plays in conjunction with the current stop.
    function makeArray() {
    this.length = 0;
    }
    function makeTourStop(url, desc, mult) {
    this.url = url;
    this.desc = descFrameTop + desc + descFrameBottom;
        if (mult != null) this.mult = blankFrameTop + '' + blankFrameBottom;
        else this.mult = blankFrame;
    this.display = displayStop;
    }
    function newTourStop(url, desc, mult) {
    cur++;
    tourStops.length = cur;
    tourStops[cur] = new makeTourStop(url, desc, mult);
    }
Function newTourStop() simplfies the whole process by "storing" the object in an array for easy playback. The small makeArray() function is a trimmed down version of the usual arrray constructor. This pseudo-array maker doesn't automatically assign the length of the array; if you look closely at the code, you'll see that newTourStop() takes care of that.

    function displayStop() {
    nurl = baseHREF + this.url;
    ndesc = this.desc;
    nmult = this.mult
    parent.pageview.location = nurl;
    parent.description.location = 'javascript:parent.ndesc';
        if (!musicEnabled) 
        parent.music.location = 'javascript:parent.blankFrame';
        else if (nmult != lastMus && musicEnabled) 
        parent.music.location = 'javascript:parent.nmult';
    }
The last part of the tour object displays the tour in its respective frames, using the tried and true
location method. The first three lines of the function simply extract the values of url, desc, and mult into three temporary variables. The location of the main frame, named pageview, is given the value of url. This takes care of displaying the current page. Next, the description (or annotation) that you specify to go along with that page is printed in the side frame, description. Finally, if you specify any music to be played, the script will create an embed and print it to the hidden frame; music. The embed's autostart propery is set to true, which gives the effect of on-demand audio.
Running the Tour

The actual running of the tour; advancing, backing up, and toggling the music, is done by the three functions: backTour(), contTour(), toggleMus(). These functions are pretty self-explanatory. Function contTour(), which advances the tour, jumps to the next element in the array (meaning the next tour stop) every time it runs. The back up function does the exact opposite. The toggleMus() function simply toggles the music on and off.
    function backTour() {
        if (curStop > 1) { 
        lastMus = tourStops[curStop].mult;
        curStop--;
        tourStops[curStop].display();
        }
    }
    function contTour() {
        if (curStop  0) lastMus = tourStops[curStop].mult;
        curStop++;
        tourStops[curStop].display();
        }
        else parent.location = lastStop 
    }
    function toggleMus() {
        if (!musicEnabled) {
        musicEnabled = true;
        lastMus = '';
        }
        else musicEnabled = false;
    tourStops[curStop].display();
    }

Customizing the Tour

To create a new tour stop, all you need is two pieces of information (or three if you want music) to pass newTourStop(). The first piece of information contains the name of the HTML document that you want displayed in the main frame. This can be any page on your site that you want to showcase. The second contains the comments and images that you want displayed in the side frame: just include plain old HTML. The final value that you pass is the name of the MIDI file that you want to play in the background. If you specify the same MIDI file two or more times, it will automatically continue to play. If you specify none, then the tour will play nothing.
    newTourStop('index.html', '<B>Welcome</B> to the Tour.', 'relief1.mid');
    newTourStop('tip_week_past.html', 'Welcome to The Repository.', 'relief1.mid');
    etc...
There are two pages that you need to modify to make the tour work for you. These are not separate HTML documents; they are stored in strings. The first two strings contain the header and footer of the commentary frame. They can simply consist of a opening HTML tags, a header graphic, and a closing HTML tag at the bottom.
    var descFrameTop = '<HTML><BASE HREF = "' + baseHREF + 
    '"><BODY BACKGROUND = "bg.gif"><IMG HEIGHT = 109' +
    'WIDTH = 145 SRC = "tourhead.gif"><BR><BR>';
    var descFrameBottom = '</BODY></HTML>';
    var descFrame = descFrameTop + descFrameBottom;
The second page contains the three control buttons: Back Up, Continue, and Toggle Music. The image file names and their respective heights and widths are the only parts of the string that need to be modified:
    var controlFrame = '<HTML><BASE HREF = "' + baseHREF + '">' +
    '<BODY BACKGROUND = "bg.gif" TEXT = "#000000"' +
    'LINK = "#B8860B" ALINK = "#8B0000" VLINK = "#B8860B">' +
    '<A HREF = "javascript:parent.backTour()"' +
    'onMouseOver = "parent.status = \'Back up one stop.\'; return true;">' +
    '<IMG BORDER = 0 HEIGHT = 27 WIDTH = 81 SRC = "backup.gif" HSPACE = 2></A>' + 
    '<A HREF = "javascript:parent.contTour()"' +
    'onMouseOver = "parent.status = \'Continue on to next stop.\'; return true;">' +
    '<IMG BORDER = 0 HEIGHT = 27 WIDTH = 81 SRC = "continue.gif"></A>' +
    '<A HREF = "javascript:parent.toggleMus()"' +
    'onMouseOver = "parent.status = \'Toggle Music [on/off].\'; return true;">' +
    '<IMG BORDER = 0 HSPACE = 2 HEIGHT = 19 WIDTH = 61 SRC = "music.gif"></A>
    '</FONT></BODY></HTML>';
Finally you have to print the frames that go along with the tour. As long as the frame names are left unchanged, the actual layout of the rows and columns is completely irrelevant. In other words, you can change the layout to your heart's desire.
    document.write ('<FRAMESET onLoad = "contTour()" COLS = "210,*"'>');
    document.write ('<FRAMESET ROWS = "0, *, 70">');
    document.write ('<FRAME NAME = "music" SRC = "javascript:parent.blankFrame">'); 
    document.write ('<FRAME NAME = "description" SRC = "javascript:parent.descFrame">'); 
    document.write ('<FRAME NAME = "control" SRC = "javascript:parent.controlFrame">'); 
    document.write ('</FRAMESET>');
    document.write ('<FRAME NAME = "pageview" SRC = "javascript:parent.blankFrame">'); 
    document.write ('</FRAMESET>');


Source