Setting User Data
Java's "write once, run everywhere" approach is in general implemented adequately enough (see minor counterexample) so that JDoc and JSite will work using the default user data (currently browser="IE 4" and platform="Win 95") and supplying this information as described below is unnecessary. However if you wish to use EarthStones' HTML+ conditional inclusion feature to select by browser and platform values, the above approach must be implemented in the applet's tag.
In the latter case EarthStones' applets rely upon javascript to furnish these two pieces of information: the identity of the user's browser and the computing platform on which it is running. These data are supplied using javascript's navigator object which has the following two very useful properties:
navigator.appName
(e.g., returns Netscape or Microsoft Internet
Explorer)
navigator.appVersion (e.g., returns
4.01 [en] (WinNT; I) for Navigator 4.01 running on
Windows NT)
To illustrate, the HTML document JSite.htm, home of JSite's <applet> tag, defines two javascript functions browser() and platform() (along with some helper functions) which extract the desired information from the navigator property strings. For details, inspect that code.
The following javascript wrapper is then used to pass these data on in the <applet> tag:
<script><!--
var str = "<BODY bgcolor='#FFFFFF' scrolling='no'
noresize marginwidth=0 marginheight=0>" +
"<APPLET CODE='earthstones.JSite.class' WIDTH=1024
HEIGHT=610 name='JSiteApp' codebase='java'>" +
"<param name='platform' value='" + platform() +
"'>" +
"<param name='browser' value='" + browser() +
"'>" +
"</APPLET>";
document.write(str);
//--></script>
Finally, EarthStones' own website launches JSite in a slightly more complicated way by loading the file index.html (found in your EarthStones/html subdirectory) which defines main and dummy frames and then loads JSite.htm into the former. The reason for this extra step is to circumvent what has been called the boundary offset problem (see discussion of this topic on EarthStones' website at About this Web Site/Un- (or Obscurely-) Documented Tips and Tricks) created by the fact that Internet Explorer and Netscape Navigator define document margins in different ways.
To see the effects of this discrepancy, load the following two pages http://www.stephenschultz.com/index.html (this is the same as loading http://www.stephenschultz.com on our server) and http://www.stephenschultz.com/JSite.htm in different browsers. Loading index.html produces the same result in all browsers. In the case of JSite.htm, however, Navigator 4 shows no page offset while Navigator 3 and Explorer 4 will display the page offset down and to the right (but by different amounts).
In addition, all three browsers will add unnecessary horizontal and vertical scroll bars to the page that themselves eat up screen real estate. The only way to force the browser to omit the scrollbars is to adopt the frames approach of index.html and use the scrolling="no" noresize attributes in the <frame> tags.
So, the extra step of using index.html to load JSite.htm sidesteps both the browser offset and scrollbar problems. Because the various browsers seem to have endless ways of idiosyncratically implementing HTML, index.html resorts to using two frames where it would appear than one would do. This matter is discussed elsewhere.