3. Module layout

(you would do well to be at a computer for reference while reviewing this section)

At right is a screen-shot of a project Links module in the revised (July 1999) navigational format. Functionally it consists of 3 frames which are sized based on the navigational components included in the upper-left corner frame. Navigation is dealt with entirely within the index.html file.

The script include file /devmodules/shared/navigation/navigation.js provides functions and variables for the HTML programmer to use to specify navigation parameters in the index.html file. After all navigation data has been specified, the function buildNavigation() is called. This function constructs the frames, produces content in the two frames on the left, and loads the start.html page into the content frame.

As with other standard Links code, the most efficient way to implement this navigation scheme is to copy the code of an existing navigation setup and modify it to fit your module. View the source of the Template index file at
http://links.math.rpi.edu/devmodules/template/index.html

Consider printing out a copy to have with you as you review the rest of this primer section.

All navigation data is entered by using JavaScript functions or by setting variables. In an effort to ensure consistancy among all Links modules, all module index.html files will reference the same navigation.js script include file. This file will manage all navigation formatting. Accordingly, should changes be necessitated in the navigation, ALL modules will be changed by changing only the one file. This also puts an absolute clamp on formatting: no longer will some modules have titles centered and others left-justified, some link, some not, etc. ALL modules will ALWAYS be 100% consistant once converted.

The following parameters must be set for all modules:

Parameter Name How used Example
moduleTitle this string is used in the window title as well as in the navigation frame. moduleTitle = "Vibrating Strings";
copyrightYear used in the copyright notice at the bottom of the bottom navigation frame. Specify the year(s) using a string. copyrightYear = "1998-1999";
addHeading(titleString, linkURL); specifies text to use in the side navigation bar's table of contents for a heading, and the URL to link to when that text is pressed. addHeading("Introduction", "intro.html");
addSubHeading(titleString, linkURL); specifies text to use in the side navigation bar's table of contents for a sub-heading, and the URL to link to when that text is pressed. addSubHeading("An example", "example.html" );
addHeadingAsPopUp(titleString, linkURL); specifies text to use in the side navigation bar's table of contents for a heading, and the URL to link to when that text is pressed. URL will open in a new window. addHeadingAsPopUp("Pop-Up Header", "popUpHeader.html");
addSubHeadingAsPopUp(titleString, linkURL); specifies text to use in the side navigation bar's table of contents for a sub-heading, and the URL to link to when that text is pressed. URL will open in a new window. addSubHeadingAsPopUp("Pop-Up SubHeader", "popUpSubHeader.html" );

notes:


troubleshooting:


Take a look at the side bar at left. Notice the prior/next button set, the tracks, and the arrow in the table of contents. Each of these three components is optional and controlled by parameters through the index.html file. Use of any or all of these is entirely at the discretion of HTML and content developers.


Using bullets

To include the bullets in the table of contents (indicating the page the user is currently on), include the following line in your setup code:

bulletsUsed = true;

Using prior/next buttons

Doing this requires both setting the control variable

prevNextUsed = true;

and specifying the page sequence. The latter is done by creating an array of strings, each of which is a URL. Review the example below. The array may be any size you like. Note that the variable name of the array must be pageSequenceArray

var pageSequenceArray = new Array("page1.html", "page2.html", ...);

Using tracks

The most complex of the three components; also the least frequently used. To use tracks, first set the control variable as follows

tracksUsed = true;

Next, set the button graphic references. Use the function

setTrackStateButtons(textLabel, disabled_icon, enabled_icon, selected_icon);

for each track in the module. For example, the code

setTrackStateButtons("undamped", "shared/navigation/graphics/undampedD.gif", "shared/navigation/graphics/undampedE.gif", "shared/navigation/graphics/undampedA.gif");

setTrackStateButtons("damped", "shared/navigation/graphics/dampedD.gif", "shared/navigation/graphics/dampedE.gif", "shared/navigation/graphics/dampedA.gif");

is used for undamped and damped tracks in the mechanical-oscillations flavored modules. Similar to the calls to the addHeading() and addSubHeading() functions, the tracks are laid out (left to right) in the order in which the function setTrackStateButtons() is called.

Finally, track pages must be associated with their respective tracks. Please review the following code.

trackArray = new Array();

trackArray[0] = new Array("mathAnalysis_apply1.html", "mathAnalysis_collab1.html", "mathAnalysis_concepts1.html", null, "mathModel_concepts1.html", "mathModel_collab1.html", "mathModel_practice1.html");

trackArray[1] = new Array("mathAnalysis_apply2.html", null, "mathAnalysis_concepts2.html", "mathAnalysis_practice2.html", "mathModel_concepts2.html", "mathModel_collab2.html", null);

Notice the 2-dimensional structure of the array:
pages in trackArray[0] are associated with the first track, pages in trackArray[1] with the second track, etc. Also note that pages with the same index number in trackArray[0] and trackArray[1] contain the respective track version of the same content page.

Pages which exist in one track, but not another should have null used as the URL for tracks in which it does not exist. Pages not using the track sequence need not be included in the trackArray[]'s.

The defaultLink() function is no longer supported. Include track pages in the addHeading() and addSubHeading() functions just as you would any other page, and the navigation construction will configure it appropriately. You will notice that links for track pages call the function top.goTrackLink( defaultURL );. This will take the user to the defaultURL if no track is currently active, or (if a track is active) will take you to the selected content page for that track.

Take a look at the Vibrating Strings module at
http://links.math.rpi.edu/devmodules/mechanicalosc/vibstring/NEWindex.html

It uses all three navigational components. Navigate through the track structure. Take a look at the URL in the status bar that comes up on mouse-over of the titles in the table of contents--you'll notice the call to top.goTrackLink(); for Math Model and Math Analysis. Now look at the index.html file to see how it was all put together.
The mechanisms to construct navigation make certain assumptions about files your module has and about their location.

In the html/ directory you must have:

page name function
start.html first content page loaded in
crib.html module crib sheet
library.html module multimedia library
map.html module map

And, of course, the module's index.html file must be in its root directory.
Modules are also equipped with navigation along the top of the mid_content labeled frame. Each bar is embedded into the HTML code of the page currently showing in that frame. Its format is as follows:


Each word links to a seperate page which is a sub-section of each topic in the table of contents. The word list concepts, discover, applications, collaborate, practice is hard wired as such. The character in front of concepts, and the red coloring of that word in the sample top bar shown above indicates to the user that she is on that page currently. Blue colored links indicate active links, while gray links indicate inactive links (those not linked to another page).

To create the navigation bar on the top of each content page, use the JavaScript function makeNavigationBar();. This function takes either 0 or 5 arguments. If passed 0 arguments, as just shown in its definition, it creates a top-navigation bar with all links grayed out. Passing 5 names of HTML files (links to correspond to each identifier: i.e. the first argument (link) will be referred to and the corresponding document opened when the user clicks on concepts, the second link used for discover, and so on.) The function will determine and account for indicating the current page to the user with coloring and symbol. If you have documents for only some of the links, use the argument null for those pages to which you have no link. Please refer to the example below (page naming convention is discussed later in this section).

Example:
To obtain the example navigation bar shown above, we would use the following code:
<SCRIPT>
  makeNavigationBar("toc1_concept.html", null, "toc1_apply.html", "toc1_collab.html", "toc1_practice.html");
</SCRIPT>

Module organization is as follows:

concepts 
discover 
applications 
collaborate 
practice 
toc* entry 1
         
toc entry 2
         
...
         
toc entry n
         
* toc : table of contents

Where each blank square in the diagram represents a possible page. That is to say: for each entry in the table of contents in the left-hand navigation bar, there are up to five possible links for that topic. The default link (for example, if the user clicks on the topic in the side navigation bar) is usually to the concepts page, though this is at the discretion of the content developers.

Not all module pages adhere to this formatting. For example, the Introduction and Objectives pages are likely to have no links, in which case they will have a top navigation bar with all links grayed out. For consistency, we do include the top-navigation bar in all module pages even when it goes unused

As this matrix organization fashion has the potential to introduce confusion and disorganization in the naming of files, a protocol has been established. For each topic, a word-string of approximately 8 letters is constructed. To this string, an underscore and the topic sub-section identifier are concatenated. This is demonstrated below.


VERY IMPORTANT With the implementation of our new navigation scheme (July 1999), it is important to have a unique word-string for each side-navigation bar table of contents entry. The navigation mechanism that determines bullet (arrow) placement in beside the current topic depends on your following this convention. You must also not use any underscore ("_") characters in your word-string or in the corresponding html file name, at the risk of the bullets misbehaving.
The metadata.html file contains information about the contents of the module as well as its development status. You may use the file at http://links.math.rpi.edu/devmodules/template/metadata.html as a template for constructing your module's metadata.html file. This file is to be stored in the module's root directory.

Familiarize yourself with the Links module version standard, available at http://links.math.rpi.edu/webhtml/versionkey.html.

Copyright © 1999 Rensselaer Polytechnic Institute. All Rights Reserved.