Before You Start

Downloading Joust

When you download Joust, you will receive a ZIP file (or self extracting executable) containing the following files:

index.htm This is the main HTML page that contains most of the Joust code and sets up the frames.
index2.htm This page sets up the separate window for Floating Mode.
index3.htm This is the home page of the No-Frames version of your site (if you choose to have one).
menu.htm This is the menu frame.
menucntrl.htm This is a sample menu control page.
title.htm This is a sample title page.
home.htm This is a sample home page.
robots.htm File used by search engines to index your site.
page1.htm This is a sample page for the sample menu.
page2.htm This is a sample page for the sample menu.
page3.htm This is a sample page for the sample menu.
page4.htm This is a sample page for the sample menu.
license.htm The legal stuff.
readme.txt Miscellaneous information like how to find us.
images This is a directory containing all the GIF images you need to get started.

Once you have downloaded Joust, fill in our mailing list page so that we can keep you informed of future developments (only about a dozen messages a year).

Things You Should Know

Joust is written in JavaScript (that's JavaScript, not Java). We have tried to make it easy to install and configure Joust with as little knowledge of HTML and JavaScript as possible. However, it is impossible to do this completely and there are a few things you will need to understand before you start.

JavaScript
You don't need to know JavaScript but you should have an idea of what it is and where it fits in the overall scheme of things. You should also be familiar with some basic programming concepts and be able to recognise things like a variable, a function call and an 'if' statement. If you have done any sort of scripting or programming before then you will be OK.

If you are interested in finding out more about JavaScript then a good tutorial can be downloaded from TrainingTools.com. A very good source of information on JavaScript, for everyone from beginners to advanced developers can be found at irt.org. I strongly recommend the article JavaScript Guidelines and Best Practice by Martin Webb for anyone interested in writing cross-browser JavaScript (both new and experienced developers).
Frames and Framesets
The Joust environment is built using a number of Frames and Framesets. If you want to make changes to the basic look of the environment, you will need to understand how the <FRAMESET> and <FRAME> tags work. There are some very good tutorials on the subject of Frames in the Mikodocs Guide to HTML, Ben Ziskind's Advanced HTML Tips and Tricks and in the Webreference HTML tutorial You've been Framed. WebReference also have a good tutorial on using JavaScript with Frames here.
URL's
You may think that you understand these, but many of the problems reported to us are caused by incorrect links. You should understand what the different parts of a URL are. In particular, make sure you understand what is meant by absolute and relative paths and how the behaviour of these can change when accessing a file from a local disk (instead of a web server) with certain browsers. The NCSA (at UIUC) Beginner's Guide to HTML contains a good introduction to URL's in part 2. I have yet to find a discussion of how different browsers behave when given a partial URL in a page that was originally loaded directly from a file. One day I might find the time to write one - in the meantime just remember that there is no standard defined for this situation so every browser treats it differently.

Modifying Joust For Your Needs

Most of the JavaScript code that makes up Joust can be found in the index.htm file. Near the top of this file you will see a HTML comments section containing the Joust version and copyright notice. This is what we refer to as the "Start of Joust" marker. Approximately 850 lines below this you will see a line like this:

##################   End of Joust   ##################

This is what we refer to as the "End of Joust" marker. The index2.htm and menu.htm files both have similar markers. Most (but not quite all) of the JavaScript code that makes up Joust is between these markers. You should not attempt to modify anything between the start and end markers unless you know what you are doing.

Below the "End of Joust" marker in index.htm, there are two functions that you will need to modify to customise Joust to your requirements. These are initOutlineIcons and initialise and look something like this:

function initOutlineIcons(imgStore) {

    ...

}
function initialise() {

    ...

}

Much of the following documentation explains how to understand, and modify what you see inside these functions.

Important Note: The location of the </HEAD> and <BODY> tags within index.htm and index2.htm is important. Many WYSIWYG editors (like Microsoft FrontPage and Netscape Composer) think that the structure of these files is wrong and try to move these tags. This will break Joust on Netscape browsers (MSIE seems to be more tolerant of the incorrect HTML syntax that results). Do not edit index.htm or index2.htm with one of these editors (these files do not produce anything that is visible to a user so there is no need to use a WYSIWYG editor anyway).

The Joust Outliner