Home | Downloads | Outline Browser |     Share This Page

Outline Browser documentation/support

Outline Browser is a Java applet that can be hosted on your page. It reads a plain-text data file from your site and generates an outline of your site's contents, with descriptive comments and active links.

Outline Browser is CareWare .

If you are reasonably computer-skilled, putting this applet on your site should be as simple as 1,2,3:

1. Download the package outline.zip , which contains all necessary files and a copy of this document.

2. Install
  • 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 .
3. Test
  • 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!
At this point, the most computer-skilled will have a working applet and will know how to edit the site map. For the rest of you,

4. The Gory Details
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.
You should realize that Outline Browser has about a million

5. User-settable options
Each option appears enclosed within the APPLET tag as a PARAM tag. Examples are shown here in color:

<applet
		code=outline.class
		name=outline
		width=240
		height=370 MAYSCRIPT>
	<param name="datafile" value="samplemap.txt">
	<param name="targetpage" value="newWindow">
</applet>
                  
The parameter names must be entered in lowercase.

Here is a complete list:

Parameter Name Default Value Comment
arrowrightname (undefined) A graphic file name for the right-pointing arrow symbol, by default generated internally.
arrowdownname (undefined) A graphic file name for the down-pointing arrow symbol, by default generated internally.
itemdotname (undefined) A graphic file name for the dot symbol, by default generated internally.
textfontface Helvetica The font face for the item text. In Java, the choices are Courier, Dialog, Helvetica, and TimesRoman.
titlefontface Helvetica The font face for the titles (section headings). See above for acceptable names.
textfontstyle plain The style of the text font. Acceptable values are plain, bold, italic, and bolditalic. The last value mixes the bold and italic styles.
focustextstyle bold The style of the text font when the item has focus (when the mouse is over it). See above for acceptable values.
titlefontstyle bold The style of the title (section heading) font. See above for acceptable values.
focustitlestyle bold The style of the title (section heading) font when the title has focus. See above for acceptable values.
textfontsize 12 The point size of the text font.
focustextsize 12 The point size of the text font when it has focus.
titlefontsize 14 The point size of the title font.
focustitlesize 16 The point size of the title font when it has focus.
bulletcolor #0000ff The color of the internally generated bullet (dot) symbol. The entry format is the one common on Web pages, and most good editors provide a way for you to select this color using a graphic dialog.
arrowcolor #400040 The color of the internally generated arrows.
bgcolor #ffffff The color of the applet's background, usually chosen to blend into your page's background.
textcolor #000000 The color of the item text.
shadowcolor #c0c0c0 the color of the dropshadow seen on the titles and internally generated graphics
titlecolor #004000 The color of the title text.
focusbgcolor #ffffc8 The background color of an item when it has focus.
focustextcolor #c00000 The color of the item text when it has focus.
focustitlecolor #800000 The color of the title text when it has focus.
rolltime 3 In seconds, this is the time delay after which the descripton on the status bar is replaced with the URL.
labelvsize 20 This is the pixel height for the items and titles in the list. Larger font sizes wil require larger pixel heights.
Labelhsize 400 This is the pixel width of items in the list, but this value is preliminary and is adjusted to the actual width of the displayed characters. This should be set to the maximum required width of the longest text.
labelindent 16 This is the pixel indentation for each subsection of the map.
shadowdelta 2 This is the pixel offset of the drop shadow. Set this value to 0 to prevent shadow generation.
relativepath "../" This value adjusts the addresses of all the local items in your site map. For example, if you have an item with the relative address "index.html", this default setting will look for it at "../index.html". This arrangement works if the outline applet is located in a subdirectory. If it is not, set this value to "".
targetpage "wmain" This value determines the name of the browser window that new URLs are launched into. In a frames application, name the target window when you set up the frames, and then provide the name using this parameter. If you want to launch URLs into the same window as the applet, set this value to "".
datafile "sitemap.h" The default name of the site map file. This file can have any name you choose, with any suffix. Just make sure the file itself and this tag both specify the same name.
dotcircle true A boolean value that, if true, draws a circular bullet (dot) for the item lists. If false, a square is drawn. In very small sizes, the square may look better. This option only applies to the internally generated graphics.
usecookies true A boolean value that, if true, allows Outline Browser to set and read a cookie in the visitor's browser. This allows the state of the outline to be maintained between visits, a convenient feature. To use this feature, your APPLET tag must have the MAYSCRIPT option set. See the above examples.
expandstring "Expand All" A string value that appears at the top of the display when global list expansion is possible. This value is included to allow non-English users of Outline Browser to customize this message.
collapsestring "Collapse All" A string value that appears at the top of the display when global list collapse is possible. This value is included to allow non-English users of Outline Browser to customize this message.
intranet false A boolean value that, if set true, prevents a bug that comes up if Outline Browser is run on a pure intranet — a site with no Internet access.
At this point, you pobably want to ask about

6. Support
  • 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.

These Pages Created and Maintained using   Arachnophilia.

Home | Downloads | Outline Browser |     Share This Page