• Unpack outline.zip using a reliable 32-bit ZIP program such as WinZIP .
• Create a subdirectory at your site (if possible). Let us say that you have named this subdirectory "outline."
• Place the .class files from the ZIP package into the outline subdirectory. The files should be:

  outline.class
  treeNode.class
  ParseData.class
                          

• If problems arise during this phase, read The Joys of FTP .

• Create a sample site map as a normal text file and save it in the subdirectory. Let us say our sample is called "samplemap.txt". Let's say it looks like this (there is a copy of this sample in the ZIP file):

  ROOT { My Web Site|An active outline of my Web site!|2
  	NETRESOURCES { Useful Internet Resources|Some BIG companies on this list.
  		Microsoft|The 400-pound gorilla|http://www.microsoft.com
  		Netscape|The 90-pound gorilla|http://www.netscape.com
  	}
  	NEWS { News|Some online information resources|1
  		ABC News|One of the better-organized sites|http://www.abcnews.com
  		CNN Interactive|CNN's online version|http://www.cnn.com
  		MSNBC|Microsoft's collaboration with NBC|http://www.msnbc.com
  	}
  	PERSONAL_LINKS { My Favorite Places|Places that I have found useful.|1
  		Switchboard|Big directory|http://www.switchboard.com
  		EMAIL { Email addresses|people I might want to write
  			Bill Gates|Has more money than the poorest 40% of Americans|mailto:billg@microsoft.com
  			Bill Clinton|Doesn't he live in Washington?|mailto:billc@whitehouse.gov
  		}
  	}
  	SEARCH_ENGINES { Web Search Engines|How to locate practically anything.|1
  		AltaVista|Very popular engine|http://www.altavista.digital.com
  		Inference Engine|A new, powerful engine|http://www.infind.com
  		Northern Light|Another interesting engine|http://www.nlsearch.com
  	}
  }
                      

• Create a sample HTML page that includes this applet call (in this example, the HTML page is located in the same subdirectory as the applet):

  <applet
  		code=outline.class
  		name=outline
  		width=240
  		height=370 MAYSCRIPT>
  	<param name="datafile" value="samplemap.txt">
  	<param name="targetpage" value="newWindow">
  </applet>
                        

• Test the applet:

• Voila!

a. Editing the site map

• Sections
  • Section headings consist of an internal name, a label, a description, and an optional "open-flag" that is set to "1" if this section is to be opened initially, and "2" if this section should always be open (cannot be closed).
  • Each section encloses some items with two "{,}" curly braces:

    INTERNALNAME { Label|Description|Open-flag
    	(...items...)
    }
                                

  • To separate the label, description, and open-flag, use the "|" pipe symbol. This means the pipe symbol cannot be used for any other purpose.
  • To put sections "inside" each other, simply "nest" them:

    MAINSECTION {
    	SUBSECTION {
    		SUB-SUBSECTION {
    			(...)
    		}
    	}
    }
                                

    This is how the e-mail section was made a subsection of the personal links category in the example file.

  • The internal names are for your reference, they are not displayed.
  • The labels appear on the outline display and the descriptions appear on the browser status line (at the bottom of the display).

• Item Entries
  • An item entry is placed inside a section:

    SECTION { Section Label|Section Description|Open-flag
    	Item Label|Item Description|Item URL
    }
                                

  • Each item entry consists of a label, a description, and an URL (an Internet address). Note that in an item entry, the URL occupies the same position as the open-flag did in the section heading.
    Here is a working example:

    NETRESOURCES { Useful Internet Resources|Some BIG companies on this list.|1
    	Microsoft|The 400-pound gorilla|http://www.microsoft.com
    	Netscape|The 90-pound gorilla|http://www.netscape.com
    }
                                

  • To refer to a resource on your own site, use relative addressing (no "http://" prefix):

    My Home Page|You should't miss this!|index.html
                                

b. Problems that may come up

• Relative Addressing
  In order for Outline Browser to launch your site's pages, it needs to find them. By default, the applet assumes that your site map file's local resource addressing is based on your root directory, but is located with the applet in a subdirectory. This is the default configuration. If you cannot create subdirectories and the applet and the site map are located in the root directory of your site, you will need to add one parameter to the applet tag:

  <param name="relativepath" value="">
                          

  The default relative path is "../", which has the effect of "backing up" one directory in resolving the address of a local resource.
  Of course, you can simply add the specifier for a local address path to the original data in the site map, but this is less flexible — you may need to move Outline Browser itself, and this method allows you to globally change the addressing with a single change.

• Applet Size
  Java Applets are fixed in size after they have been placed on a page — they cannot make themselves bigger to accommodate more data. So, as time passes and you add more information to your site map, you will need to adjust the applet's size. Adjust the two numbers shown in color below:

  
  <applet
  		code=outline.class
  		name=outline
  		width=240
  		height=370 MAYSCRIPT>
  	<param name="datafile" value="samplemap.txt">
  	<param name="targetpage" value="newWindow">
  </applet>
                          

• Java Security Issues
  Because of security constraints in Java, all site map files must be located in the same directory as the Java applet that requires them. This means that, if you have created a subdirectory called "outline," as in this example, all map files must be located in that subdirectory.
  You may call the applet from anywhere, any number of times, so you only need one copy of Outline Browser and as many map files as required, all located in the applet's subdirectory. Here is how to call Outline Browser from elsewhere on your site. In this example, you want to call Outline Browser from an "adjacent" subdirectory. Note the colored portion:

  
  <applet
  		code=outline.class
  		codebase=../outline
  		name=outline
  		width=240
  		height=370 MAYSCRIPT>
  	<param name="datafile" value="data.txt">
  	<param name="targetpage" value="newWindow">
  </applet>
                          

  If you can't figure out how to specify the codebase, simply use this rule: if you need to move to a directory's "parent," use "../" as many times as necessary, then specify the path from there to the subdirectory in question. In a rather extreme example, let's say the calling HTML page is located in a subdirectory five "tiers" away from your site's root directory, and (for some reason) Outline Browser is also five tiers away from the root. Here is how you would specify the codebase:

  codebase=../../../../../tier1/tier2/tier3/tier4/tier5
                          

• The Joys of FTP
  Most installation problems arise from an error in uploading the Java class files to one's Web site. You must use a modern 32-bit FTP client program, and a 32-bit unZIP program such as WinZIP , you must upload the files using "binary mode," (read the HELP file in your FTP program to learn about this), and you must not change the names of the files. You can't even change the case of the letters in the file names. I cannot stress this point too much -- the uploaded files must be identical in every way to the originals .

• Netscape and GIFs
  I discovered many things while developing this applet, not all of them fun and entertaining. One of these is that Netscape 4.04's Java machine cannot cope with transparent GIFs. This was one reason I created internal graphics — I just couldn't get the appearance I wanted from external graphics.

<applet
		code=outline.class
		name=outline
		width=240
		height=370 MAYSCRIPT>
	<param name="datafile" value="samplemap.txt">
	<param name="targetpage" value="newWindow">
</applet>
                  

• If this documentation is not enough information for you to get the applet working, please do not write and ask for help. Instead, read a book about HTML and/or Java, take a course, do some hacking (that word once meant a creative interaction with a computer).
• To report a bug in the applet, not to ask for installation help , use my Message Page . Do not write to report a bug if the problem is actually your knowledge level.