Using the Graphical Toolbox in a browser

This section describes how to convert the simple panel from the Graphical Toolbox Example to run in a browser. The minimum browser levels supported are Netscape 4.05 and Internet Explorer 4.0. In order to avoid having to deal with the idiosyncrasies of individual browsers, it is recommend that your applets run using Sun's Java Plug-in. Otherwise, you will need to construct signed JAR files for Netscape, and separate signed CAB files for Internet Explorer.

Constructing the applet

The code to display a panel in an applet is nearly identical to the code used in the Java application example, but first, the code must be repackaged in the init method of a JApplet subclass. Also, some code was added to ensure that the applet panel is sized to the dimensions specified in the panel's PDML definition. Here is the source code for the example applet, SampleApplet.java.

import com.ibm.as400.ui.framework.java.*;

import javax.swing.*;
import java.awt.*;
import java.applet.*;
import java.util.*;

public class SampleApplet extends JApplet
{
    // The following are needed to maintain the panel's size
    private PanelManager        m_pm;
    private Dimension           m_panelSize;

    // Define an exception to throw in case something goes wrong
    class SampleAppletException extends RuntimeException {}

    public void init()
    {
        System.out.println("In init!");

        // Trace applet parameters
        System.out.println("SampleApplet code base=" + getCodeBase());
        System.out.println("SampleApplet document base=" + getDocumentBase());

        // Do a check to make sure we're running a Java virtual machine that's compatible with Swing 1.1
        if (System.getProperty("java.version").compareTo("1.1.5") < 0)
            throw new IllegalStateException("SampleApplet cannot run on Java VM version " + 
                                            System.getProperty("java.version") +
                                            " - requires 1.1.5 or higher");

        // Instantiate the bean object that supplies data to the panel
        SampleBean bean = new SampleBean();

        // Initialize the object
        bean.load();

        // Set up to pass the bean to the panel manager
        DataBean[] beans = { bean };

        // Update the status bar
        showStatus("Loading the panel definition...");

        // Create the panel manager. Parameters:
        // 1. PDML file as a resource name
        // 2. Name of panel to display
        // 3. List of data objects that supply panel data
        // 4. The content pane of the applet

        try { m_pm = new PanelManager("MyGUI", "PANEL_1", beans, getContentPane()); }
        catch (DisplayManagerException e)
        {
            // Something didn't work, so display a message and exit
            e.displayUserMessage(null);
            throw new SampleAppletException();
        }

        // Identify the directory where the online help resides
        m_pm.setHelpPath("http://MyDomain/MyDirectory/");

        // Display the panel
        m_pm.setVisible(true);
    }

    public void start()
    {
        System.out.println("In start!");

        // Size the panel to its predefined size
        m_panelSize = m_pm.getPreferredSize();
        if (m_panelSize != null)
        {
            System.out.println("Resizing to " + m_panelSize);
            resize(m_panelSize);
        }
        else
            System.err.println("Error: getPreferredSize returned null");
    }

    public void stop()
    {
        System.out.println("In stop!");
    }

    public void destroy()
    {
        System.out.println("In destroy!");
    }

    public void paint(Graphics g)
    {
        // Call the parent first
        super.paint(g);

        // Preserve the panel's predefined size on a repaint
        if (m_panelSize != null)
            resize(m_panelSize);
    }
}

The applet's content pane is passed to the Graphical Toolbox as the container to be laid out. In the start method, the applet pane is set to its correct size, and then override the paint method in order to preserve the panel's size when the browser window is resized.

When running the Graphical Toolbox in a browser, the HTML files for your panel's online help cannot be accessed from a JAR file. They must reside as separate files in the directory where your applet resides. The call to PanelManager.setHelpPath identifies this directory to the Graphical Toolbox, so that your help files can be located.

HTML tags

Because it is recommended to use Sun's Java Plug-in to provide the correct level of the Java runtime environment, the HTML for identifying a Graphical Toolbox applet is not as straightforward as preferred. Fortunately, the same HTML template may be reused, with only slight changes, for other applets. The markup is designed to be interpreted in both Netscape Navigator and Internet Explorer, and it generates a prompt for downloading the Java Plug-in from Sun's Web site if it's not already installed on the user's machine. For detailed information on the workings of the Java Plug-in see the Java Plug-in HTML Specification.

Here is the HTML for the sample applet, in the file MyGUI.html:

<html>

<head>
<title>Graphical Toolbox Demo</title>
</head>

<body>
<h1>Graphical Toolbox Demo Using Java(TM) Plug-in</h1>
<p>

<!-- BEGIN JAVA(TM) PLUG-IN APPLET TAGS -->

<!-- The following tags use a special syntax which allows both Netscape and Internet Explorer to load -->
<!-- the Java Plug-in and run the applet in the Plug-in's JRE.  Do not modify this syntax.            -->
<!-- For more information see http://java.sun.com/products/jfc/tsc/swingdoc-current/java_plug_in.html.-->

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
        width="400"
        height="200"
        align="left"
        codebase="http://java.sun.com/products/plugin/1.1.3/jinstall-113-win32.cab#Version=1,1,3,0">
    <PARAM name="code"     value="SampleApplet">
    <PARAM name="codebase" value="http://www.mycompany.com/~auser/applets/">
    <PARAM name="archive"  value="MyGUI.jar,jui400.jar,util400.jar,x4j400.jar">
    <PARAM name="type"     value="application/x-java-applet;version=1.1">

    <COMMENT>
    <EMBED type="application/x-java-applet;version=1.1"
           width="400"
           height=200"
           align="left"
           code="SampleApplet"
           codebase="http://www.mycompany.com/~auser/applets/"
           archive="MyGUI.jar,jui400.jar,util400.jar,x4j400.jar"
           pluginspage="http://java.sun.com/products/plugin/1.1.3/plugin-install.html">
        <NOEMBED>
    </COMMENT>
        No support for JDK 1.1 applets found!
        </NOEMBED>
    </EMBED>
</OBJECT>

<!-- END JAVA(TM) PLUG-IN APPLET TAGS -->

<p>
</body>
</html>

It is important that the version information be set for 1.1.3.

Installing and running the applet

Install the applet on your favorite Web server by performing the following steps:

1. Compile SampleApplet.java.
2. Create a JAR file named MyGUI.jar to contain the applet binaries. These include the class files produced when you compiled SampleApplet.java and SampleBean.java, the PDML file MyGUI.pdml, and the resource bundle MyGUI.properties.
3. Copy your new JAR file to a directory of your choice on your Web server. Copy the HTML files containing your online help into the server directory.
4. Copy the Graphical Toolbox JAR files into the server directory.
5. Finally, copy the HTML file MyGUI.html containing the embedded applet into the server directory.

Now you are ready to run the applet. Point your Web browser to MyGUI.html on the server. If you do not already have the Java Plug-in installed, you will be asked if you want to install it. Once the Plug-in is installed and the applet is started, your browser display should look similar to the Figure 1:

Figure 1: Running the sample applet in a browser