Chapter 47

Developing with LiveConnect

by Jim O'Donnell

• What Is LiveConnect?
  • Enabling LiveConnect
  • The Java Console
• The netscape Packages
• JavaScript to Java Communication
• Java to JavaScript Communication
• JavaScript and Plug-Ins
  • Determining What Plug-Ins Are Installed
  • Client-Supported MIME Types
  • Calling Plug-In Functions from JavaScript
• LiveConnect Examples
  • The Envoy Plug-In by Tumbleweed
  • mBED Software
  • PointPlus Plug-In Viewer

Netscape's support for three key Web and Web browser technologies-JavaScript, Java, and plug-ins-has helped to make this the most popular Web browser. With version 3.0 of Navigator, Netscape has introduced LiveConnect, a technology that allows JavaScripts, Java applets, and Navigator plug-ins to communicate with one another. By their authors taking a few simple steps, JavaScripts, Java applets, and plug-ins can achieve full communication and cooperation with on another.

What Is LiveConnect?

Since its introduction, Netscape has introduced many new technologies into its Navigator Web browser. In addition to HTML extensions such as frames and tables, and more recent multimedia capabilities such as LiveAudio, LiveVideo, and Live3D, there have been three technologies in particular that were introduced, or first became widely used with Netscape Navigator. These are Web browser scripting with JavaScript, Java applet support, and Web browser plug-ins.

Until the release of Netscape Navigator 3, these technologies suffered from the handicap of being completely separate applications within a Web browser. JavaScripts, Java applets, and Navigator plug-ins ran within Navigator on their own, without the capability to interact. However, with Navigator 3, Netscape has introduced its LiveConnect technology allowing its three systems to interact.

Figure 47.1 shows how LiveConnect works within the Netscape Navigator runtime environment. JavaScripts can call Java methods and plug-in functions. Java applets can call both JavaScript and plug-in functions. Plug-ins can call Java methods and, through Java, call JavaScript functions. The objects and properties of each LiveConnect-compatible Java applet and plug-in are available to be manipulated through JavaScripts, applets, and other plug-ins.

Figure 47.1 : Netscape's LiveConnect technology allows JavaScript, Java, and plug-ins to work together within Netscape Navigator.

Enabling LiveConnect

By default in Netscape Navigator 3.0, Java and JavaScript are enabled-whenever these languages are enabled, LiveConnect is enabled as well. To confirm that they are enabled in your copy of Navigator, choose Options, Network Preferences and select the Languages tab. Make sure that the Enable _Java and Enable JavaScript boxes are checked, and click OK.

The Java Console

Netscape Navigator has a Java Console that can be displayed by choosing Options, Show _Java Console. Messages sent using java.lang.System.out or java.lang.System.err will appear in this console.

Now, because of the communication that is possible between JavaScript and Java using LiveConnect, messages can be sent to the Java Console from JavaScript, as well. To write a message to the Java Console from JavaScript, use the println method of java.lang.System.out or java.lang.System.out as in the following:

java.lang.System.err.println("JavaScript checkpoint #1")

The netscape Packages

Netscape Navigator 3.0 includes several Java packages that are used to enable LiveConnect communication. The first, netscape, is used to enable communication back and forth between JavaScript and Java applets. Additionally, replacement java and sun packages are provided that feature security improvements for LiveConnect. The following netscape packages are included:

• netscape.javascript  This package implements the JSObject and JSException classes, which allow Java applets to access JavaScript properties and throw exceptions when JavaScript returns an error.
• netscape.plug-in  This package implements the Plugin class, which allows cross communication between JavaScript and plug-ins. Plug-ins must be compiled with this class to make them LiveConnect compatible.
• netscape.applet and netscape.net  These are direct replacements for the sun.applet and sun.net classes provided in Sun's Java Development Kit.

JavaScript to Java Communication

With LiveConnect, JavaScript can make calls directly to Java methods. As shown in the " The Java Console" section earlier, this is how JavaScript can output messages to the Java Console. To JavaScript, all Java packages and classes are properties of the Packages object. So the full name of a Java object in JavaScript would be something like

Packages.packageName.className.methodName.

Java applets can be controlled through JavaScript without knowing too much about the internal construction of the applet, as long as a few conditions are true. The first step is to attach a NAME attribute to the <APPLET> tag when including the Java applet in your HTML document. Then all public variables, methods, and properties of the applet are available for access to JavaScript.

The Java applet is included in the HTML document using the following:

<APPLET NAME="NervousApplet" CODE="NervousText.class" WIDTH=400 HEIGHT=50>
<PARAM NAME=text VALUE="Enter your text here.">
</APPLET>

The name NervousApplet attached to the applet is how the Java applet is controlled. When the Click Here to Change Text button is clicked, the public Java method changeText is called through the following:

<INPUT TYPE=BUTTON WIDTH=200 VALUE="Click here to change text."
    onclick="document.NervousApplet.changeText(form.InputText.value)">

So for this to work, the changeText Java method needs to be defined as a public method; it then takes the text supplied and uses the applet to display it (see Figure 47.2). The changeText method is defined as a public method:

Figure 47.2 : JavaScript is LiveConnect's link between the HTML form user input and Java applets.

// This is the method that will be called by JavaScript
public void changeText(String text){
   stop();
   s = text;
   separated = new char [s.length()];
   s.getChars(0, s.length(), separated, 0);
   start();
}

Java to JavaScript Communication

The first step in allowing your Java applets to access JavaScript properties is to import the javascript package into your Java applet:

import netscape.javascript.*

This enables the Java applet to access JavaScript properties through the JSObject class. However, the author of the HTML document must still allow access to his or her JavaScript by including the mayscript attribute in the <APPLET> tag used to include the Java applet.

If these two conditions have been satisfied, accessing JavaScript objects or methods is a two-step process, as follows:

1. Get a handle for the Navigator window containing the JavaScript objects or methods you want to access. This can be done using the getWindow() method on the netscape.javascript.JSObject package:
   // winhan is a variable of type JSObject
   public void initialize() {
   winhan = JSObject.getWindow(this);
   }
2. To access JavaScript objects and properties, do the following:
3. Use the getMember() method in the netscape.javascript.JSObject package to access each JavaScript object in turn. To access the JavaScript object document.testForm, using the window handle found in Step 1, you could do the following:
   public void accessForm(JSObject winhan) {
   JSObject myDoc = (JSObject) winhan.getMember("document");
   JSObject myForm = (JSObject) myDoc.getmember("testForm");
   }
4. To call a JavaScript method: Use either the call() or eval() methods of the netscape.javascript.JSObject class. The syntax for the two commands (using the window handle found in Step 1) is as follows:
   winhan.call("methodName",arguments)
   winhan.eval("expression")
5. In the former, methodName is the name of the JavaScript method, and arguments is an array of arguments to be passed on to the JavaScript method. In the latter, expression is a JavaScript expression that, when evaluated, has a value that is the name of a JavaScript method.

JavaScript and Plug-Ins

JavaScript can be used with the client to determine what plug-ins the client has installed and what MIME types are supported. This is done through two of the navigator object's properties, plugins and mimeTypes. JavaScripts can also be used to call plug-in functions.

By determining at the client whether a particular plug-in is installed or MIME type supported, you can write scripts that generate content dynamically. If a particular plug-in is installed, the appropriate plug-in data can be displayed; otherwise, some alternative image or text can be shown.

For instance, if you have developed an inline VRML scene to embed in a Web page, you might want to know whether the user has a plug-in installed that supports VRML 1.0, VRML 2.0, or none at all. Then an animated VRML 2.0 world, a static VRML 1.0 world, or a representative GIF can be displayed, as appropriate, like the following:

<SCRIPT LANGUAGE="JavaScript">
<!-- Hide script from incompatible browsers
var isVrmlSupported,VrmlPlugin
isVrmlSupported = navigator.mimeTypes["x-world/x-vrml"]
if (isVrmlSupported) {
   VrmlPlugin = navigator.mimeTypes["x-world/x-vrml"].enabledPlugin
   if (VrmlPlugin.name == "Live3D Plugin DLL")
      document.writeln("<EMBED SRC='dynamic.wrl' HEIGHT=200 WIDTH=400>")
   else
      document.writeln("<EMBED SRC='static.wrl' HEIGHT=200 WIDTH=400>")
}
else
   document.writeln("<IMG SRC='world.gif' HEIGHT=200 WIDTH=400>")
<!-- -->
</SCRIPT>

Determining What Plug-Ins Are Installed

The navigator.plugins object has the following properties:

• description  A description of the plug-in, supplied by the plug-in itself
• filename  The file name on disk in which the plug-in resides
• length  The number of elements in the navigator.plugins array
• name  The plug-in's name

Listing 47.1 shows an example of a JavaScript that uses the navigator.plugins object to display the names of the installed plug-ins right on the Web page. This JavaScript can be placed at the bottom of any Web page to display this information (see Figure 47.3).

Figure 47.3 : The navigator. plugins object allows you to use JavaScript to determine whether a plug-in is installed.

Listing 47.1  Plugin.htm-JavaScript to Detect Locally Installed Plug-Ins

<HTML>
<HEAD>
<TITLE>JavaScript Plug-Ins Check</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1>JavaScript Plug-Ins Check</H1>
<SCRIPT LANGUAGE="JavaScript">
<!-- Hide script from incompatible browsers
var i,n
n = navigator.plugins.length
document.writeln("<HR>")
document.writeln("This Web browser has " + n + " plug-ins installed:<P>")
for (i=0;i<n;i++)
   document.writeln(navigator.plugins[i].name + "<BR>")
document.writeln("<HR>")
<!-- -->
</SCRIPT>
</BODY>
</HTML>

Client-Supported MIME Types

The navigator.mimeTypes object is very similar to the navigator.plugins object and can be used to determine supported MIME types at the client. It has the following properties:

• description  A description of the MIME type
• enabledPlugin  A reference to the particular navigator.plugins object that handles this MIME type
• length  The number of elements in the navigator.mimeTypes array
• suffixes  A string listing the file name extensions, separated by commas, for this MIME type
• type  The MIME type name (for example, x-world/x-vrml)

Listing 47.2 shows an HTML document that contains a JavaScript that displays all of the client-supported MIME types in an HTML table. Along with the MIME type, the supported file extensions are shown, as well as the name of the associated plug-in, if any (see Figure 47.4).

Figure 47.4 : JavaScript can use the navigator.mimeTypes to determine the built-in MIME type support in the client Web browser.

Listing 47.2  Mimetype.htm-JavaScript to Detect Locally Supported MIME Types

<HTML>
<HEAD>
<TITLE>JavaScript MIME Types Check</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1>JavaScript MIME Types Check</H1>
<SCRIPT LANGUAGE="JavaScript">
<!-- Hide script from incompatible browsers
var i,n
n = navigator.mimeTypes.length
document.writeln("<HR>")
document.writeln("The following MIME types are recognized:<P>")
document.writeln("<TABLE BORDER>")
document.writeln("<TR><TH>MIME Type</TH><TH>Extensions</TH><TH>" +
   "Associated Plug-In (if any)</TH></TR>")
for (i=0;i<n;i++)
   if (navigator.mimeTypes[i].enabledPlugin)
      document.writeln("<TR><TD>" + navigator.mimeTypes[i].type +
         "</TD><TD>" + navigator.mimeTypes[i].suffixes + "</TD><TD>" +
         navigator.mimeTypes[i].enabledPlugin.name + "</TD></TR>" )
   else
      document.writeln("<TR><TD>" + navigator.mimeTypes[i].type +
         "</TD><TD>" + navigator.mimeTypes[i].suffixes +
         "</TD><TD></TD></TR>" )
document.writeln("</TABLE>")
document.writeln("<HR>")
<!-- -->
</SCRIPT>
</BODY>
</HTML>

Calling Plug-In Functions from JavaScript

For plug-in variables and methods to be accessible from JavaScript and Java applets, the plug-in must be LiveConnect compatible, associated with the netscape.plugin.Plugin Java class. If that is true, the plug-in variables and methods are available to JavaScript, in much the same way as the public variables and methods of Java applets are.

There are two ways to access and control compatible plug-ins active in the Web environment through JavaScript. Similar to Java applets, the first is to use the NAME attribute of the <EMBED> tag to give a name to the embedded document. This allows the plug-ins functions to be accessed through the document object. For instance, if NAME=myenvoydoc is used with the <EMBED> tag to embed an Envoy document using the Envoy Viewer plug-in, then the viewer functions can be accessed using the document.myenvoydoc object.

It is possible to access plug-ins even if they are not named, using the embeds array of the document object. If an Envoy document is the first embedded document in the Web page, it can be accessed with document.embeds[0].

LiveConnect Examples

The cross-communication possible between JavaScript and Java is fairly straightforward. Adding plug-ins to the mix only makes things slightly more complicated. The most important thing necessary is for plug-in developers to make their plug-ins LiveConnect compatible. Netscape maintains a Web site containing a LiveConnect showcase, a list of links to other Web sites that feature demos of LiveConnect compatible plug-ins for Netscape Navigator.

The Envoy Plug-In by Tumbleweed

Tumbleweed Software is the maker of the Envoy portable document format. Tumbleweed's Web site maintains a complete catalog of its Envoy products for creating and viewing documents in the Envoy format (see Figure 47.5). Their Envoy Viewer is a freeware product, available as a stand-alone program, an ActiveX Control for Microsoft Internet Explorer, and a plug-in for Netscape Navigator. Tumbleweed has now made its Navigator plug-in LiveConnect compatible, and maintains a set of demos showing how the plug-in can be controlled and manipulated through user input and JavaScript.

Figure 47.5 : Tumbleweed has made its Envoy Viewer plug-in for Netscape Navigator LiveConnect compatible.

Controlling a Web Presentation  Figure 47.6 shows an embedded Envoy document in a Web page, set up to display a presentation over the Web. The key to manipulating the plug-in to control the display of the document is using the NAME attribute of the <EMBED> tag; then plug-in functions can be called using this name. In this example, the embedded Envoy document is named myenvoydoc.

Figure 47.6 : JavaScript timers and JavaScripts attached to HTML forms buttons can be used to control an Envoy presentation.

A series of JavaScript functions attached to each of the buttons shown in the Web page is used to carry out the functions of displaying the presentation. For instance, the following function is called when the Start button is clicked:

// Start to auto page
function start() {
   running = true;
   setTimeout("autoRun()",timer);
}

The start() function sets the running flag to true and sets up the autoRun() function to be called after the timer has expired. The autoRun() function is as follows:

// Flip next page and prepare the next timer
function autoRun() {
   if (running) {
      nextPage();
      setTimeout("autoRun()", timer);
   }
}

If the presentation is running, the autoRun() function calls the nextPage() function to advance the page being displayed and sets up the timer to call itself again.

The nextPage() function is the one that actually calls the plug-in functions setDocumentPageCount() and setCurrentPage(). It keeps a running count of the current page being displayed and calls setCurrentPage() to display it. When getDocumentPageCount() reveals that the end of the presentation has been reached, the page number is reset to the beginning and the presentation is started again. The nextPage() function is as follows:

// Move the next page and wrap around at the end
function nextPage() {
   page++;
   if ( page >= document.myenvoydoc.getDocumentPageCount() ) page = 0;
      document.myenvoydoc.setCurrentPage(page);
}

Mouse Interaction  The example shown in Figure 47.7 shows a clever way to use Envoy to display context-sensitive information on the Web page. Each of the country hypertext links shown is set up to call the JavaScript function show() when the mouse passes over the following link:

Figure 47.7 : JavaScripts can be used with the HTML onMouseOver property to display context-sensitive information via Envoy.

<A HREF="lc.htm" onMouseOver="show(8)">Canada</A>

As in the preceding example, an Envoy document has been embedded into the Web page and given the name myenvoydoc. This document contains pictures of the flags of the countries listed on the page. The show() function then uses the setCurrentPage() function of the Envoy plug-in to display the appropriate page in the document, which would be that country's flag:

function show(num) {
   if (num != current) {
      current = num;
      document.myenvoydoc.setCurrentPage(current);
      document.myenvoydoc.executeCommand(COMMAND_FIT_HEIGHT);
   }
}

Note that the Envoy Viewer plug-in function executeCommand() allows the plug-in functions to be called based on pre-defined command numbers (defined by the plug-in). COMMAND_FIT_HEIGHT is a constant (the numerical value 601, which corresponds to the Envoy Viewer fit-to-height command) defined in the JavaScript to call the Envoy Viewer function to fit the document page to the current height of the embedded window.

Designing a Custom GUI  JavaScript and HTML forms and other elements can be used to access all of the commands of the Envoy Viewer plug-in, which are normally only available by right-clicking the embedded Envoy document within the Web page. By making these commands accessible to JavaScript, a custom user interface to the Envoy Viewer commands can easily be constructed.

Figure 47.8 shows a displayed Envoy document. The icons on the bottom are images used as hypertext links, with Envoy Viewer commands attached to their onclick attributes.

Figure 47.8 : Any of the functions of the Envoy plug-in are accessible to Java and JavaScript.

For instance, the fit-to-height button (see Figure 47.9) is defined with a hypertext link:

Figure 47.9 : JavaScript and HTML elements can be used to fashion a custom user interface to the Envoy plug-in capabilities.

<A HREF="nothing.htm"
     onclick="document.myenvoydoc.executeCommand(601);return false;">
    <IMG SRC="width.gif" ALT="Fit Width" BORDER=0 WIDTH=26 HEIGHT=26>
</A>

Note that the actual link is a fake one-a hypertext link is used to allow the onclick attribute to be used, but clicking the actual link doesn't follow the link because of the return false command included in the onclick attribute. This button merely calls the Envoy Viewer command to fit the document to the current height of the embedded viewer window.

mBED Software

mBED Software creates mbedlets, custom embedded applications that run within Netscape Navigator for specific functions (see Figure 47.10). The mbedlets use LiveConnect technology to communicate with JavaScript and Java applets and even with one another. mBED Software maintains a set of demos that show this inter-communication possible with LiveConnect.

Figure 47.10 : mBED Software's mbedlet technology uses LiveConnect to create interactive applets that access the Internet.

The Bulls & Bears Stock Ticker  The Bulls & Bears Stock Ticker uses the methodology shown in Figure 47.11 to present a continuously updated list of stock prices in a small window that it creates from Netscape Navigator. A Java applet is used to interface between JavaScript and the user (where the desired stocks are chosen), the CGI program (where the stock information is obtained), and the mbedlet (that takes the stock data, manipulates it, and presents it in an effective fashion).

Figure 47.11 : The Bulls & Bears Stock Ticker can take user input and create a continually updated stock ticker of selected stocks.

The Bulls & Bears Stock Ticker can be launched and left running in a window of its own as long as you'd like. As long as it can periodically update its stock price information (as long as an Internet connection is maintained), it shows how the selected stocks are faring.

Johnny mbedlet  mBed Software's Johnny mbedlet is a simple little demo making use of an important capability of LiveConnect. Normally, JavaScript and (to a lesser extent) Java are the glue used to attach the different pieces together when using LiveConnect. For instance, user input is taken via an HTML form and a JavaScript is called to send the resulting data or commands to a Java applet or plug-in.

It is also possible, however, for plug-ins and Java applets to communicate with and control one another. In this demo, the figures of Johnny and Camille mbedlet represent different processes, moving back and forth in their little world. Johnny can be controlled somewhat by the user. The sliding control on the left is used to determine the speed with which Johnny moves back and forth (see Figure 47.12).

Figure 47.12 : Two separate mbedlets run side-by-side in this demonstration. The user controls the speed of Johnny mbedlet on the left.

When the user clicks Johnny, he immediately begins to chase after Camille. When he reaches the right edge of his little world, he stops. When Camille subsequently reaches the left edge of hers, she sees Johnny and makes her escape (see Figure 47.13). The user has no direct interaction with the Camille mbedlet, but his or her actions affect Camille through Johnny.

Figure 47.13 : Not only can the user interact with mbedlets via JavaScript, but two mbedlets can interact-when Camille sees Johnny chasing her, she makes her escape.

While this is something of a silly example, the possibilities that it opens are very interesting. LiveConnect allows JavaScript, Java applets, and plug-ins to interact. Usually this is done through JavaScript, but it can also be done between the other pieces. Plug-ins can be used to control other plug-ins, for instance. This can be used to design sophisticated interfaces to link together and control multiple plug-ins.

PointPlus Plug-In Viewer

Net-Scene's PointPlus allows the creation and viewing of animations created from PowerPoint presentations on the Web. Its PointPlus Plug-In Viewer is available for free and allows these presentations to be seen (see Figure 47.14).

Figure 47.14 : PointPlus makes tools for creating and viewing animated PowerPoint presentations on the Web.

Because the PointPlus Plug-In Viewer is LiveConnect compatible, it can interact with JavaScript and Java applets. Net-Scene has included a couple of demos available through its Web site that shows how to control the presentation through either a Java applet or JavaScript.

Java Viewer Control  The PointPlus animated presentation is embedded in the Web page using the <EMBED> tag, as follows:

<EMBED name=css SRC=mex.css WIDTH=500 HEIGHT=250 MOUSE=OFF CYCLE=NO>

The NAME attribute is used to provide the access into the plug-in's functions. The Java applet presentation control is included using the following HTML code (see Figure 47.15):

Figure 47.15 : LiveConnect allows the Java applet at the bottom of this Web browser window control over the presentation.

<APPLET CODE=Player.class codebase="classes" WIDTH=350 HEIGHT=70 MAYSCRIPT>
<PARAM NAME=bgcolor VALUE=black>
<PARAM NAME=loadplay VALUE=false>
<PARAM NAME=filebase VALUE="files">
<PARAM NAME=csslist VALUE="mex.css|coke.css">
<PARAM NAME=titlelist VALUE="Mexican food|Always CocaCola">
</APPLET>

The Java applet accesses the plug-in functions through the css name and allows the user to proceed through the presentation, move forward or backward, ask for information about the viewer, or even load a new presentation (see Figure 47.16).

Figure 47.16 : Java user input windows can be used to solicit input and load new presentations.

JavaScript Viewer Control  The same functions available through Java applets can also be controlled through JavaScripts. As shown in the Java Viewer Control in the previous section, the PointPlus presentation is embedded with HTML similar to

<EMBED name=css SRC=intro.css WIDTH=400 HEIGHT=300 mouse=off cycle=yes>

JavaScripts attached to the graphics implement the different functions. For instance, the button to move to the next slide is implemented as follows:

<A HREF="javascript:document.css.goForward(1)"
    onMouseOver="top.window.status='go to next slide';return true;">
   <IMG SRC="forward.gif" BORDER=0>
</A>

Rather than using a fake URL for the hypertext link attached to the button, a new format URL javascript:document.css.goForward(1) is used to call the plug-in function directly to move the slide ahead one. The onMouseOver attribute is used to update the status bar message to reflect what button the mouse is currently over (see Figure 47.17).

Figure 47.17 : Through LiveConnect technology, JavaScripts attached to the graphics and HTML forms elements can be used to control the PointPlus Viewer.

As with the Java Viewer Control, it is possible to also load and view a completely different presentation. In this case, it has been implemented with an HTML forms drop-down menu (see Figure 47.18).

Figure 47.18 : With a forms drop-down menu, a new presentation is a few mouse clicks away.