Applets are black-box programs that can be executed within a web page by a Java-enabled browser. This document explains how to invoke applets from HTML. It begins with a discussion of applet tags and parameters, and then explains how to invoke a remote applet from your local web pages.

The <applet> Tag

An applet invocation is specified using the pair of tags <applet> and </applet>. The <applet> tag has four attributes:

• code : The name of the Java bytecode (.class) file to execute.
• codebase : The URL (absolute or relative) of the directory containing the code file.
• width: The width of the window "pane" within which the applet will be displayed.
• height: The height of the window "pane" within which the applet will be displayed.

The code, width, and height attributes are all required. The optional codebase attribute is perhaps the trickiest aspect of calling an applet and deserves special attention. The value of the codebase attribute is always the name of a directory, and never the name of a file. So a codebase attribute never ends in an extension (e.g., .html, .class, .java). The value of the codebase attribute depends on the relationship between the locations of the bytecode file and the HTML file invoking the bytecode file:

• On different machines: If the bytecode file resides on a machine different from that of the HTML file invoking it, codebase must be the absolute URL of the directory containing this file. An absolute address has the form http://machine-name/directory-path. For example, here is the applet tag for an HTML file invoking a bytecode file from the java/assorted/Coalesce directory at www.vivids.com:

        <applet codebase="http://www.vivids.com/java/assorted/Coalesce/" 
                code=Coalesce.class 
                width=400
                height=200>

• In the same directory : If the bytecode file and the HTML file invoking it reside in the same directory on the same machine, then the codebase attribute can be omitted. If it is not omitted, it should be the empty string, "". For example, the test.html invoking CX121Applet.class contains the applet tag:

        <applet code=CX121Applet.class width=400 height=200>

• In different directories on the same machine: If the bytecode file and the HTML file invoking it reside in different directories on the same machine, the value of the codebase attribute is usually a relative URL. Relative URLS are of the form dir₁/dir₂/.../dir_n , where dir_i is either a directory name or the special parent token ".." (pronounced "dot-dot"). A relative URL specifies a path from the directory containing the HTML file to the directory containing the code file. Each parent token ".." in the path means "ascend to the parent of the current directory", while each directory name dir means "descend to the subdirectory named dir within the current directory". Consider the relative URL for each of the following placements of a file test.class and a file test.html that invokes it:

Location of test.class	Location of test.html	Value of codebase attribute within test.html
/applets/programs/examples	/applets	programs/examples
/applets/programs	/applets	programs
/applets/programs	/applets/html	../programs
/applets/programs/examples	/applets/html	../program/examples
/applets/programs	/applets/html/examples	../../programs
/applets/programs/examples	/applets/html/examples	../../programs/examples

Parameters

The behavior of an applet can be controlled by any number of parameters chosen by the implementor of the applet. Each parameter is specified by the following syntax, of which any number of instances (including zero) may appear between the <applet ...> and </applet> tags:

<param name=parameter-name value=parameter-value>

For example, here is the HTML code that invokes a MoveUp.class in the same directory as the HTML file:

<applet code=MoveUp.class width=250 height=50>
<param name=TextCount value=2>
<param name=text1 value="Twinkle, twinkle">
<param name=text2 value="little star">
<param name=AppBGImage value=../images/pattern.gif>
<param name=AppTile value=true>
<param name=DelayBetweenChars value=50>
<param name=DelayBetweenRuns value=2000>
<param name=HorizCenter value=true>
<param name=VertCenter value=true>
<param name=Font value=Helvetica>
<param name=Style value=bold>
<param name=Pointsize value=30>
</applet>

The names of the parameters are important. For example, one cannot rename text1 to text when there is only one line of text.

The names, possible values, and meanings of each applet parameter are chosen by the creator of the applet. A good applet programmer will associate documentation for this information with each applet. Given just a Java bytecode file, there is no easy way to tell exactly what parameters it handles.

How to Invoke an Applet you Find on the Web

Suppose you find a cool applet on the web that you would like to include in your own set of pages. How can you accomplish this? To understand the issues involved, it is important to realize that an applet usually consists of more resources than just a single .class file:

• It may require other .class files in addition to the particular .class file that is invoked.
• It may require data files (e.g. images and sound files) in addition to the code files.

The failure to correctly handle these additional resources is a common reason why an applet does not work when you attempt to include it in your personal web pages.

There are two basic approaches to including a remote applet in your personal pages:

1. Copy all the relevant code and data files to the machine with your web pages. You must be careful to maintain the relative directory structure of all these files if you expect them to work together. Many applet publishers make it easy for people visiting their sites to download applets in this fashion.
2. Leave the code and data files on the remote machine an refer to them via global URLs.

Each of these approaches has advantages and disadvantages. The first approach requires the overhead of first copying all the applet resource files to your local machine. This goes against the grain of the entire applet notion, which is to dynamically download programs from the web. Leaving applets on the web saves space on your local machine and allows applet users to always get the "latest version" of the applet. On the other hand, repositories for web applets can become temporarily or permanently inaccessible, so it can be prudent to make local copies of applets that you find indispensable and that you fear might disapper from the web.

For the rest of this section, we assume that you are following approach 2: that is, you want to invoke an applet whose .class file and other resources are on a remote machine. We also assume that you can successfully execute the desired applet by following some set of links in your web browser. That is, you found the applet on someone else's web page and want to include it in your own. The following steps explain how to invoke the applet from one of your personal pages:

1. Follow whatever links are necessary to successfully execute the desired applet. When the applet is executing, your browser is at a particular web page. Let's refer to the global URL for this page as dir-name/page-name, where dir-name is a global URL for the directory containing the current web page and page-name is the name of the current page. For example, dir-name might be http://www.vivids.com/java/assorted/Coalesce/ and page-name might be Coalesce.html.
2. The page you are viewing (such as those on the Instant Java website) may include instructions for how to invoke the applet. For example, it may include sample <applet ...> and <param ...> tags and documentation about the meaning of parameters. This information is important for understanding the meaning of parameters. However, such instructions usually assume that you are downloading a local copy of the applet to your machine. Since we will not be following that strategy here, you should ignore what the documentation says about the codebase tag and parameters that refer to various resource files instead, figure out how to handle these based on the following steps.
3. See how the page you are currently viewing is invoking the desired applet by viewing the document source in the browser and finding the appropriate applet invocation tags in the source. Copy these tags to the local page from which you wish to invoke the applet. Let's refer to the local copy as the applet invocation template. Your goal now is to modify the template so that the applet can be successfully invoked from your local page.
4. Do not change the code attribute. The template already has the correct value for this attribute from the remote page.
5. Determine the correct value for the codebase attribute. This is done by combining the name of the remote directory (dir-name, from above) and the value of the codebase attribute on the remote page (let's call its valuecodebase-name)
   • If there is no codebase attribute on the remote page, then set the value of the codebase attribute in the template to be dir-name.
   • If codebase-name is an absolute URL (i.e., http://...), then set the value of the codebase attribute in the template to be codebase-name.
   • If codebase-name is a relative URL, then set the value of the codebase attribute in the template to be the result of extending dir-name with the relative path information in codebase-name.If codebase-name is just a sequence of directory names, append this sequence to the end of dir-name, ensuring that there is exactly one slash character, /, between dir-name and the sequence of directories in codebase-name. If codebase-name begins with a sequence of parent tokens, .., then each such token indicates the removal of one directory name from the end of dir-name.

     Here are some examples of extending dir-name with codebase-name. In all cases, assume that dir-name is http://www.cool.com/applets/examples.

     Remote codebase-name	Template value for codebase attribute
     test	http://www.cool.com/applets/examples/test
     test/code	http://www.cool.com/applets/examples/test/code
     ../test/code	http://www.cool.com/applets/test/code
     ../../test/code	http://www.cool.com/test/code

6. The final step is determining how to address remote data resources, such as image and audio files. This step can be even trickier than determining the correct local value for the codebase attribute! The problem is that addressing remote data resources depends on how the applet programmer referred to these resources when implementing the applet. Even worse, the implementation decisions of the applet programmer aren't always apparent from the invocation tags or documentation for the applet. There are several possible cases:
   • Case 1: The data resources are located in fixed locations relative to remote codebase directory and are not user-settable parameters. If there are no parameter tags mentioning image files, audio files, etc., this is hopefully the case. In this case, there is no need to do anything special; setting the codebase attribute in the previous step is all that is necessary.
   • Case 2: The data resources are located in fixed locations relative to the HTML file containing the applet invocation tags. This case cannot be distinguished from Case 1 by examining the applet invocation tags. Unfortunately, in this case it is impossible to address the data resources at their remote location. Instead, it is necessary to copy the remote resources to the local machine, maintaining their locations relative to the local HTML file. If documentation about the resources and their lcoations does not exist, this step may not be possible.
   • Case 3: The data resources are located in files that are specified in <param ...> tags. Such parameters often have names like img, image, image-file, image-directory, etc. Suppose that the value of such a paramter is resource-name. Then in the local applet invocation template, it is necessary to replace resource-name by the result of extending dir-name by resource-name. See the previous step for an explanation of what it means to extend a directory name by a file name. For example, the MoveUp.class example given earlier contained the parameter

      <param name=AppBGImage value=../images/pattern.gif>

     Suppose the remote directory containing the HTML file with this tag is named http://www.vivids.com/java/assorted/MoveUp. Then in the local applet invocation template, the above parameter should be changed to

         <param name=AppBGImage 
                value="http://www.vivids.com/java/assorted/images/pattern.gif">

Java-Challenged Browsers

Not all web browsers are Java-enabled. A significant number of people surfing the web use text-only browsers (such as Lynx), or older versions of graphical browsers (Netscape, Internet Explorer, Mosaic) that do have support for running applets. Browsers typically ignore tags that they do not implement, so by default these browsers give no indication that there is an applet invocation on a web page that cannot be handled.

It is helpful to give users of Java-challenged browsers an indication that there is an applet on the page that they are not seeing. There are two ways of doing this:

1. While not implementing applets, some browsers understand an alt attribute for the applet tag. This is a string that will be displayed instead of running the applet. For example:

         <applet code=CX121Applet.class width=400 height=200
                 alt="Here is an applet that displays the phrase
                      Welcome to CX121">
         </applet>

   It is worth noting that most browsers understand a similar alt attribute for the img tag. This is helpful not only for text-only browers, but also for graphical browsers that for some reason cannot find the image.

2. Most Java-enabled browsers ignore all text between the <applet ...> and </applet> tags except for <param ...> tags. This means that any text between this two tags will be displayed by Java-challenged browsers but not Java-enabled ones. For example:

         <applet code=CX121Applet.class width=400 height=200>
         Because you are running a Java-challenged browser, you
         are missing out on a wonderful applet that displays the
         message "Welcome to CX121" in glorious colors. 
         </applet>