Java Site Explorer (JavaSex) applet user manual Version: 1.0 build 004 (release) 26 October 1999 copyright © the Java hermit Web: http://www.celticedge.com/hermit/index.html E-mail: hermit@celticedge.com | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Java Site Explorer (JavaSex) must be licensed for use on commercial sites. Non-commercial users do not need a license but are required to display a credit. Please visit the Java hermit web site for current details on how to buy licenses, current license pricing and conditions of use. This software and/or it's accompanying documentation must not be sold or offered for download without authorisation. The Java hermit retains copyright and accepts no responsibility for any loss, damage or other consequence alleged to be a result of use.
JavaSex is a versatile menu/navigation applet that can be configured for use as a navigation tool for sites both large and small. The applet consists of a background container area on which a menu display window and optional buttons are laid out. Buttons are used to select different menu structures. Buttons can be omitted leaving just a single menu (but the menu can't be omitted to leave just buttons). If buttons are used there must be at least two. Menus can contain anything from a few individual selections to complex trees with nested folders. Conventional HTML applet parameters are used to supply JavaSex with customizing info on colors, graphics, fonts and other options. Info on buttons/menus structure is supplied via a simple configuration script that can be prepared using any capable text editor. Not difficult, but there are a few simple rules so it is strongly recommended that users refer to the step-by-step setup guides presented below.
Two demos are included. As JavaSex will usually be deployed in a permanently visible frame both are frame-based and visibly similar. One shows the applet driven by a configuration scipt contained in a separate file; the other shows how the same configuration data can be embedded in the HTML APPLET code (thereby avoiding the need for a separate file and making startup slightly faster)... run the configuration file demo run the embedded data demoThese two configuration data techniques are discussed in detail in the configuration scripts section below.
JavaSex consists of 8 class files with a total size of approx 35k. The two dashes -- within each filename represents the version number (e.g. javasex10.class etc. for version 1.0)... javasex--.class (main class file) javasex--a.class javasex--b.class javasex--c.class javasex--d.class javasex--e.class javasex--f.class javasex--g.classClass files are binary files. When uploaded to a web site using FTP they must be sent in binary tranfer mode. All class files must be present in the same folder for the applet to work. Here is an APPLET tag example that assumes HTML, class and all support files are in the same folder... <APPLET CODE="javasex10.class" WIDTH=150 HEIGHT=240> <!-- applet PARAMs go here --> </APPLET>WIDTH= and HEIGHT= are the applet size in screen pixels (some browsers support % sizing). CODE= refers to the applet's main class file (case sensitive and must include the .class extension). PARAMs are explained in the next section. Here is another example that includes the CODEBASE= tag to permit class and other applet support files to reside in a different folder (or even on a different server) to that containing the HTML file... <APPLET CODE="javasex10.class" CODEBASE="../class" WIDTH=150 HEIGHT=240> <!-- applet PARAMs go here --> </APPLET>... A folder named class contains the applet class files (any legal folder name can be used). CODEBASE can be an absolute (http://...) or relative URL as shown in the above example. To avoid problems relating to browser security it is recommended that all supporting files the applet requires - graphics, audio, configuration - should be located in the same folder as the .class files.
PARAMs are used to provide an applet with customization info for colors, fonts and other general options (PARAM is an abbreviation of PARAMeter). They are inserted between the <APPLET> and </APPLET> tags... <APPLET CODE="someapplet.class" WIDTH=150 HEIGHT=240> <PARAM NAME=color_menuback VALUE=#FFFFFF> <PARAM NAME=audio_button VALUE="click.au"> <PARAM NAME=scrollbars VALUE=3> </APPLET>A PARAM has two parts - a NAME and a VALUE. The NAME is an identifier which enables the applet to search for a particular name-associated VALUE. The VALUE may be a string (sequence of characters), a number or a combination of both. Applet authors tend to develop their own methods for deciding how NAMEs should be structured. JavaSex uses the following NAME conventions... NAME Describes Example ----- --------- ------- rect_xxx a rectangle NAME=rect_menu VALUE=5,5,120,200 color_xxx a color NAME=color_back VALUE=#FFFFCC font_xxx a font NAME=font_folder VALUE="Helvetica,1,12" image_xxx an image file NAME=image_icons VALUE="icons.gif" audio_xxx an audio file NAME=audio_button VALUE="click.au" xxx something else NAME=scrollbars VALUE=3Most PARAMs are optional and have a default VALUE that will be used if the PARAM is omitted. How to specify VALUEs for the various parameters will be described in detail in the sections following. All PARAMs and their default VALUEs are formally described in the tables below.
Notes:
A JavaSex configuration script is a list of instructions that contains information on button and menu captions, icons, links and hints. There are two ways a configuration script can be used - the data can be contained in a text file the applet reads on startup or specified directly in the relevent applet parameter. In both cases the appletdata parameter is used, see the working demos and below for examples of both techniques. A formal explanation of how configuration data is structured follows. Click here to view the content of the example script democfg.txt used in the file-based demo. Delimiters Four special characters are used to separate configuration data button and menu entry captions, icon references, link URLs and text hints. These characters are called delimiters and they may be set via the delimiters parameter. Most users can omit the delimiters parameter and use the predefined default set... { opening curly brace } closing curly brace + plus , comma... the only reason to change the default delimiters is if one of the characters used must be displayed in a caption or hint or is used in a URL. Users of the Java hermit TreeNav applet can reuse TreeNav config scripts by resetting the '|' delimiter to '+' (and changing MENU references to FOLDER). Configuration data structure Three special tags are used to specify buttons, menu folders and menu items... {BUTTON}...{/BUTTON} {FOLDER}...{/FOLDER} {ITEM}BUTTON and FOLDER have both opening and closing tags because they can enclose FOLDERs and ITEMs. ITEMs do not have a closing tag. All are similar in that each can include... - a caption with up to two optional icons. - a link URL with optional target. - a text hint.Here is an example (indenting is optional)... {BUTTON caption,5,6 + * + hint text} {FOLDER ~caption,1,2 + * + hint text} {ITEM caption,3,4 + URL + hint text} {ITEM caption,3,4 + URL + hint text} {FOLDER caption,1,2 + * + hint text} {ITEM caption,3,4 + URL + hint text} {ITEM caption,3,4 + URL,_blank + hint text} {/FOLDER} {/FOLDER} {ITEM caption that also displays as hint,3,4 + * + =} {/BUTTON} {BUTTON another button,5,6 + * + hint text} // more menus and items here {/BUTTON}In each configuration line (except for closing /BUTTON and /FOLDER tags) there can be three sections of information, each isolated from the next by a delimiter, here set to the default '+' character. Captions and Icons In the above example 'caption' represents a text string caption, optionally followed by up to two numbers separated by commas. These numbers refer to icon positions in the optional image_icons icon graphic file. The first identifies the icon to display when the corresponding BUTTON, FOLDER or ITEM is unselected, unopened or unvisited: The second identifies the icon to display when the corresponding BUTTON, FOLDER or ITEM is selected, open or visited. If only one icon number is specified (i.e. caption,2) that icon will be displayed for both states. To select a BUTTON or open a FOLDER on menu startup precede the caption with a '~' character, but note that if autoclose is used only one first level menu can be preset open. By default the first button found in a config script is selected on applet startup. URLs and Targets A URL can be any legal address, such as http://www.somewhere.com (an absolute address) or ../mydocs/mypage.htm (a relative address). You can omit http:// prefixes in most absolute addresses - the applet will add them automatically to any URL that begins with www or web. A target is the name of a frame or window where a linked document is to be displayed. In most cases it is not necessary to include individual targets as a global target can be specified via the deftarget parameter. To use an individual target append it to the URL using a separating comma, for example www.somewhere.com,targetname. There are 4 predefined target names: _blank means display in new browser window, _top means display in existing top level browser window, _parent means display in next window up the browser window hierarchy, and _self means display in same window (the default). Other target names are usually those set in FRAME tags, for example... <frame name="mytarget" ..... >Substitute (dummy) URLs Entries that do not include an active URL sometimes require that a single character be inserted as a 'dummy' URL. Any non-delimiter character can be used, URLs only 1 character long are ignored... {XXX caption text + * + hint text} // dummy URL required here {XXX caption text} // no hint so substitute URL not requiredHints A hint is a text string, usually used to expand on the information contained in the associated caption. To have the caption text repeated as a hint set the hint to a single equals '=' character. The hintoptions parameter sets how hints are displayed. Examples Using a configuration script file: The filename and [optional path] are specified in the appletdata parameter... <param name=appletdata value="[path/]filename">Specifying data directly: The data is written directly in the appletdata parameter... <param name=appletdata value=" {BUTTON caption,1,2 + * + hint text} {FOLDER ~caption,3,4 + * + hint text} {ITEM caption,5,6 + URL + hint text} {ITEM caption,5,6 + URL + hint text} {FOLDER caption,3,4 + * + hint text} {ITEM caption,5,6 + URL + hint text} {ITEM caption,5,6 + URL,_blank + hint text} {/FOLDER} {/FOLDER} {ITEM caption that also displays as hint,5,6 + * + =} {/BUTTON} ">Indenting and other formatting is optional as data extending over multiple lines is read as one long string. For example this is permitted... <param name=appletdata value=" {BUTTON caption,5,6+*+hint text} {FOLDER ~caption,1,2+*+hint text}{ITEM caption,3,4+URL+hint text} {ITEM caption,3,4+URL+hint text}{FOLDER caption,1,2+*+hint text} {ITEM caption,3,4+URL+hint text}{ITEM caption,3,4+URL,_blank+hint text} {/FOLDER}{/FOLDER}{ITEM caption that also displays as hint,3,4+*+=}{/BUTTON} ">Note that if a line is broken at a space within a caption or hint it may be necessary to insert a leading space in the following line to obtain correct text formatting. Why specify config data directly when using a file may be more convenient? Some firewalls (software that monitors and controls information allowed to pass between a private intranet and the public Internet) can block download of a configuration file, preventing the applet starting up. The use of firewalls is growing so, when the applet is used over the public Internet, specifying data directly may be preferable. Single menu without buttons To display a single menu without buttons omit BUTTON tags from the configuration script and use only FOLDER and/or ITEM tags.
Parameters rect_button and rect_menu are used to size and position buttons and menu on the applet background. These parameters have no default value and must be correctly specified or the applet will fail to start (rect_button can be omitted if buttons are not used). Rect_xxx parameter values require 4 numbers, for example... <param name=rect_button value=8, 10, 100, 30>...this button is positioned 8 pixels in from the applet left edge, 10 pixels down from the applet top edge, is 100 pixels wide and 30 pixels high. Rect_button sizes and positions the top button. Other buttons are automatically lined up below and the vertical space between them is set by the buttonspace parameter. The rect_menu parameter positions and sizes the menu...
Icons that are optionally displayed in button and menu captions are all contained in a single graphics file. Here is the supplied 16-color icon file jsicons20.gif (border added for clarity)... 16 or 256 color GIF files can be used for icons. The background color must be set transparent. For icons to display correctly the applet must be told how many icons a file contains, the iconcount parameter is used for this purpose. The icon file itself is specified in the image_icons parameter. To avoid possible browser security problems it is recommended that graphic files be located in the same folder that contains the applet class files.
Solid colors and/or graphics images can be used for both applet and menu backgrounds. The parameters used are... parameter name controls -------------- -------- color_back applet background solid color color_menuback menu background solid color image_back applet background graphics image image_menu menu background graphics imageNon-transparent GIF or JPEG images can be used. If no image is specified in the relevent parameter a solid color is used to paint the background. If an image is specified the backstyle and menubackstyle parameter values control how it is painted. In both parameters the following values may be specified... 0 position the image top left (the default) 1 center the image 2 tile with multiple copies of the imageTo avoid possible browser security problems it is recommended that graphic files be located in the same folder that contains the applet class files.
Sometimes it is desirable to arrange for the applet background graphic to align with an HTML document body background graphic. The topmargin and leftmargin parameters allow an applet background graphic to be offset. For example, a topmargin value of 4 will shift the painted image up 4 pixels and a leftmargin value of 3 will shift the image left 3 pixels. When using topmargin and leftmargin it is important to ensure no unwanted HTML document margins are introduced. If the menu is in a frame explicitly set the frame margins to zero or a fixed value, for example... <FRAME NAME="fmenu" SRC="menu/jsxmenu.html" MARGINWIDTH="2" MARGINHEIGHT="0">See the working demos HTML code for further examples.
The menu can be equipped with both vertical and horizontal scrollbars. The scrollstyle parameter controls them, the following parameter values can be used... 0 no scrollbars (the default) 1 show vertical scrollbar 2 show horizontal scrollbar 3 show both vertical & horizontal scrollbarsScrollbars size (width of vertical & height of horizontal) is set by the scrollsize parameter. The default is 15 screen pixels, values of between 8 and 24 may be specified. Scrollbars are purpose designed for consistent appearance and performance across platforms. The autoclose parameter can be used to control how the menu user is allowed to open folders. The default value for autoclose is zero (= off) which allows all folders to be open at the same time. When the value is set to 1 only one first-level folder can be open at any one time (a first-level folder is one that is not a nested sub-folder). When a new first-level folder is opened that previously opened is closed automatically. Using autoclose can reduce the height required by a menu in instances where, for appearance reasons, use of a vertical scrollbar is to be avoided.
The hintoptions parameter controls how hints are displayed. It's value can be one of the following... value means ----- ----- 0 all hints are turned off 1 popup hints off, hint text displays in browser status bar 2 popup hints off, link URL (if any) displays in status bar 3 hint text displays in popups and in status bar 4 hint text displays in popups, link URL displays in status barPopup hint colors and font are set by the color_hintback, color_hinttext and font_hint parameters.
Font parameter values are made up from 3 parts separated by commas. For example... <param name=font_hint value="Helvetica,0,10">"Helvetica,0,10" describes font facename, style, pointsize respecively. Available styles are... 0 plain 1 bold 2 italic 3 bold italicOnly a few font faces are guaranteed to be supported on all Java-enabled browsers. They are Helvetica, TimesRoman, Courier and Dialog (Dialog in some Netscape 3.x, 4.0x releases was unreliable due to apparently incorrect height attributes). When these fonts are not actually installed on a client machine they are mapped by Java to the nearest equivalent. Different fonts can be used for menu folders and menu items (font_folder and font_item) but fonts with large size differences should be avoided. Folder font or icon height (whichever is greater) is used to calculate all menu entry heights.
Color values in applet parameters can be decimal or hexadecimal. Decimal values require no prefix, hex values can be prefixed with 0x or #. Color names such as "Red" can't be used. To ensure colors display as accurately as possible in all browsers use those from the 216-color 'safe browser palette'. All the safe colors are contained within the standard 8-bit (256 color) GIF palette. In hexadecimal notation safe colors are built from combinations of 00, 33, 66, 99, CC and FF. For example, #3366CC is a 'safe' color but #3366DD is not. Hexadecimal colors are arranged #RRGGBB. For example in color #3366CC value 33 is the RED component, 66 is the GREEN component and CC is the BLUE component. Spectroscope, an excellent FREE utility program for selecting safe colors (Windows 95/NT), is available from http://www.headoffice.co.uk. When choosing colors for items that can have a 3D appearance, such as buttons and menu border, remember that highlight and shadow colors are automatically generated from the specified color. To generate highlight & shadow colors successfully the specified color should be medium bright.
Sounds can be attached to button presses and menu folder/item selection (see parameters audio_button, audio_folder, audio_item). Only .au format files are supported. Due to an idiosyncrasy of Java sound files are not actually downloaded from the server until they are first played. There can be an appreciable delay between, for example, first selection of a sound-enabled button and hearing the sound. Once the sound has been played there are no further delays. It's a good idea to make audio files, if any, as small as possible. To avoid possible browser security problems it is recommended that audio files be located in the same folder that contains the applet class files.
Local testing of applets in earlier browsers may prove difficult. MSIE 3 may report spurious errors that go away when online. Netscape 3.x can take some time (minutes) to initialise it's Java virtual machine when displaying local pages that contain applets. Most HTML WYSIWYG editors won't run Java applets in their internal browsers. If things are not working try the following...
It's always essential to final test over a live Internet connection (use a test page nobody else can view before you release it on the general public). Please read this documentation carefully before contacting the hermit for technical assistance. If requesting help include as much information as possible (description of problem, browser and OS details, testing online or offline?). Include a copy of your HTML and configuration script (please do not mail graphics files) and, if available, a URL to the page on which the problem occurs.
|