setup and test

 
applet class files
The SlideShow applet consists of a set of class files, each containing compiled binary data. For the applet to function all class files must be present in the correct folder or directory. Usually class files are placed in the same directory as the HTML file that contains the applet. SlideShow uses five class files, total size approx 29k:
   SlideShow.class (main class file)
   SSBase.class
   SSCanvas.class
   SSButton.class
   SSItem.class

Note: Class file names are case sensitive. Their exact spelling and capitalisation must be preserved. Note also they are binary files that must be FTP'd in binary mode to avoid corruption.
 
buttons graphic file
The four buttons (change view, previous, next, stop load) that appear bottom left of the applet use graphic images that are all contained in a single graphic file (a GIF file with, usually, a transparent background). Here is the file buttons.gif used in the applet demo (shown with border for clarity):
button icons
The top row of images represents active buttons, the bottom row represents the same buttons in a disabled state. The graphic is divided into an equal 4 x 2 grid, and can be made as large or small as required as long as each button image occupies exactly the same size area.
    Each image is automatically centered in it's button. Button sizes are not controlled by the size of the graphic - their width and height is set independently by the btnwidth and btnheight parameters.

Note: Previous versions used a graphic file called ssbuttons.gif that was required to be located in the codebase directory. In this version the graphic filename and location must be specified in the icongraphic parameter.
 

configuration data
Configuration data means the list(s) of images and text the applet is to display, and associated data such as link URLs and identification codes. All are optional - that is, images can be displayed without accompanying text and vice versa; images don't have to have associated links; identification codes are usually used only in shopping cart type applications.
    A set of configuration data can be either contained in a text file which the applet reads or specified directly in the applet parameters. In both cases the appletdata parameter is used, it's value being either the [path/]name of a data-containing file or raw configuration data. Both techniques are discussed below.
    SlideShow can be externally controlled by JavaScript to read data from more than one configuration data file. This allows presentations to be broken into logical sections. See JavaScript interface for more information.

Applet configuration data is structured using a set of HTML-like special tags <SHOW...> and </SHOW>: Each image with it's optional caption, text, link and identification code is specified between this tag pair (examples indented only for clarity)...

   <SHOW=Imagename.ext,21 | Caption | Link URL,target | ID code>
   Optional text goes here, it can extend
   over several lines. It is automatically
   reformatted by the applet.
   </SHOW>
The various terms used in the above example mean...

Imagename.ext,21 - The name (and directory, if required) of an image to display. The comma and 2-digit number ,21 refer to an optional layout for this image and it's associated text, see canvas layout.
Caption - Text that appears in applet caption bar.
Link URL,target - A URL to which the applet user is transported if the displayed image is clicked on. Can point to local or full http://... addresses. The target - the window or frame where linked pages will appear - could be a predefined window name (_top, _blank, _self or _parent) or the name given to a frame. If you set the deftarget parameter you probably won't need to specify individual targets in the data, omit the comma and target name.
ID code - A string of two characters or more that identifies the displayed material, for example ABC1, ABC2 or just 01, 02, 03 etc. See JavaScript interface for more info.

Suppose you wanted an image and an ID code, but no caption, link or text. Here is how it would look...

   <SHOW=lazydog.gif | * | * | QBF001>
   </SHOW>
The important thing is, in the SHOW tag, mark empty slots with spaces and/or a single non-space character. SlideShow trims leading/trailing spaces away and ignores the entry if less than 2 characters are left. If the empty slot(s) are trailing they can be omitted (see embedded data example below).

A complete configuration data setup would likely consist of several <SHOW...> </SHOW> pairs. For an example of how to write a text configuration file see sshermit.txt. Here is an example of how to specify such a text file in the appletdata parameter...

   <PARAM NAME=APPLETDATA  VALUE="sshermit.txt">
Below is an example of specifying the data for two images embedded directly in the appletdata parameter. Here the SHOW tag delimiters have been set to curly braces "{}" (see note below on why this might be desirable)...
   <PARAM NAME=APPLETDATA  VALUE="

 {SHOW=lazydog.gif | See the fox jump | http://www.fox.com}
 The quick brown fox jumps over the lazy dog.
 {/SHOW}

 {SHOW=quickfox.gif | See the lazy dog | http://www.dog.com}
 The lazy dog doesn't
  see the quick brown fox.
 {/SHOW}

   ">
Such embedded data should be left-justified, otherwise unwanted leading spaces may be included in the displayed text. However, if there is more than one line of text indent the second and subsequent lines by 1 space for correct text formatting. For an example of embedded data see ss_demo1.html source code.

Note: The two characters "<>" used in some of the example configuration data above are called tag delimiters. This pair is the default but a different pair can be used by specifying them in the delimiters parameter. Some HTML editors, notably MS Frontpage, like to automatically modify <tags> they don't recognise but will ignore alternative {tags}.
 

preparing images
The original intention was to provide the option to scale images to the applet canvas size. Unfortunately earlier versions of certain unnamed browsers are unreliable at image scaling so this feature will have to wait until most web users have upgraded from Netscape 3.
    Anyway, SlideShow does not scale images so users will have to resize them to fit. Images larger than the applet will display but only a partial section will be visible, probably not what is required. Images larger than the display do not scroll - only text, if any, is scrollable. See canvas layout below for image layout options.
    GIF or JPG images may be used. Most of the images used in the applet demos are JPG, saved at 300 dpi (dots per inch) with 25/1 compression. The applet will display GIF images with transparent backgrounds correctly.

Note 1: Do not test SlideShow using a series of indentical images. In some browsers and for reasons unknown (something to do with the internal workings of Java) this results in the applet stalling between image loads. All images in a presentation must be different for correct operation.

Note 2: Some image editors produce JPG images Java does not understand. Earlier versions of PhotoShop, for example, appear to suffer from this problem and there may be others.
 

canvas layout
There are two ways to specify how an image and it's associated text are laid out when displayed: The first is to specify a default layout for all, the second is to set optional individual layouts in the configuration data. Individual layouts take priority - if included they override the default.

Specifying a default layout - see deflayout parameter. Optional individual layouts can be included in configuration data by appending a comma and 2-digit number to the image file name, for example...

   <SHOW=Imagename.ext,21 ...etc...>
Here are the numbers that can be used, and what they mean...
   10  image left, text left-formatted at right.
   11  image left, text center-formatted at right.
   12  image left, text right-formatted at right.

   20  image center, text left-formatted below.
   21  image center, text center-formatted below.
   22  image center, text right-formatted below.

   30  image right, text left-formatted at left.
   31  image right, text center-formatted at left.
   32  image right, text right-formatted at left.
To indent images and text from the edges of the image/text display area (the canvas) set the canvasborder parameter.
 
visual appearance
There are several options that affect the way the applet looks. Here is a summary of the applet parameters that affect visual appearance...

External border - width is set by the borderwidth parameter. If set to zero the border is turned off. Four styles of border are available, set by the borderstyle parameter. Border color is set by the bordercolor parameter - when using 3D border styles a medium brightness color works best.

Caption panel - visibility is controlled by the showcaption parameter.

Caption and buttons panels - Background color is set by the panelcolor parameter. The captioncolor parameter controls the color of caption text (and that of hint text that appears adjacent to the buttons). Four panel border styles are available, set by the panelstyle parameter.

Canvas area - solid background color is set by canvascolor parameter. The canvas area may be tiled by a graphic, set via the canvasgraphic parameter. When a canvas background graphic is used it's a good idea to set the canvas backgound color to one that matches the overall graphic color.

Canvas layout - see canvas layout for information on how to position images and text.

Progress bar - the color of the bar that shows image download progress is set by the progresscolor parameter.

Scrollbar - width is set by the scrollwidth parameter. To turn the scrollbar off omit the parameter. Scrollbar background color is set by the scrollcolor parameter.

Note: When specifying colors use those that are included in the 'safe browser palette' to avoid dithering. Safe colors are those constructed using only the hexadecimal numbers 00, 33, 66, 99, CC and FF. For example, #6699FF is a legal safe color but #80F6D5 is not. In hexadecimal notation the leading double digit represents the red content, the middle the green content and the trailing the blue content. So the color number #FF9900 means maximum red, a moderate amount of green, and no blue.
 

applet HTML tags
The basic HTML tag set for SlideShow is as follows...
   <applet code="SlideShow.class" width=xxx height=yyy>
     <!-- parameters go here -->
   </applet>
xxx and yyy should be set to the required applet width and height in screen pixels. The above example assumes class files are located in the documentbase directory. If the class files are in a different directory include the codebase modifier...
   <applet code="SlideShow.class"
   codebase="classdir" width=xxx height=yyy>
     <!-- parameters go here -->
   </applet>
where classdir is the name (and if required the relative location) of the directory containing the class files. The codebase can also refer to an absolute full URL (http://...etc). Use of codebase sometimes causes problems with offline testing.

To use the JavaScript interface the applet must be given a name...

   <applet code="SlideShow.class"
   name="myslideshow" width=xxx height=yyy>
     <!-- parameters go here -->
   </applet>
An applet name can be any string that is not a JavaScript object name.

Note: name, code and codebase tags all refer to items that are Case Sensitive, which is why enclosing "quotation marks" are used.
 

JavaScript interface
SlideShow contains two public functions that can be called from JavaScript (see ss_demo2.html for examples of use)...
  boolean setAppletData(String sFileName)
  String getItemIdent()
setAppletData requires a string that refers to the configuration file [path/]name the applet is to use. If path information is included it should be relative to the documentbase directory. A boolean value (true or false) is returned to indicate if the request was accepted.

getItemIdent is used to return the string ID code that can be attached to displayed items (see configuration data). If an item has no identifier attached an empty string "" is returned.

Note: The applet must be given a name in order to call it's internal functions from JavaScript (see applet HTML tags).
 

upgrading from earlier versions
Here is a list of parameters that have been changed or replaced in this version...
    old parameter name   replacement

    savelastimage        instancekey
    border               borderwidth
    layout               deflayout
    center               no longer used (see canvas layout)
    percent              no longer used (see canvas layout)
    textalign            no longer used (see canvas layout)
    buttonhints          btnhints
    parabreakchar        paragraph
    fontface             no longer used (see fonts)
    fontsize             no longer used (see fonts)
    fontstyle            no longer used (see fonts)
    linecolor            no longer used
    captionbkcolor       panelcolor
    captionfgcolor       captioncolor
    textbkcolor          canvascolor
    textfgcolor          textcolor

Note 1: Older versions of SlideShow (1.10 or earlier) will not run alongside instances of this version.

Note 2: Previous versions used a graphic file called ssbuttons.gif that was required to be located in the codebase directory. In this version the buttons graphic filename and location must be specified in the icongraphic parameter. Button sizes are now independent of button icon image size and are set by the btnwidth and btnheight parameters.
 

testing
Make sure Java is enabled in your browser. Remember local testing of applets in some browsers may not work. Netscape 3.x can take some time (minutes) to initialise it's Java virtual machine when displaying local pages. Most HTML WYSIWYG editors won't run Java applets in their internal browsers. Always invoke your test page from a browser bookmark (this makes the browser think it is reading from a URL).

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).

Problems are nearly always caused by spelling mistakes, invalid directory information or case sensitivity problems.

When FTP-ing to your site ensure class files are sent in binary mode, and check your FTP program is not set to convert all filenames to lowercase (class file names are case sensitive).

There is an Applet Users Tutorial available on the Java Hermit web site. If you have problems configuring and/or testing your applets you may find some useful info there.

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 data (please do not mail graphics files) and, if available, a URL to the page on which the problem occurs.
 

 

Copyright © the Java Hermit 1998
e-mail:
hermit@celticedge.com
web: www.celticedge.com/hermit/