Incorporating JavaGrins in your web page

Introduction

Java Grins is a Java based chemical editor that derives SMILES equivalents of sketched molecules and reactions and vice versa. While it attempts to follow in the lines of its predecessors, xvgrins and cgi-grins, its user interface has been completely redesigned to conform with popular chemical sketching programs. With Java Grins version 1.0 one can

• draw a molecule or reaction and obtain its canonical SMILES representations. The molecule (or molecules if in a reaction) may be drawn with stereochemistry for tetrahedral and double bonds. The reactions may be mapped in which case mapped reactions SMILES are returned
• input a molecule smiles string and obtain a depiction of the molecule it represents. Currently the depiction does not represent stereochemical bonds as stereochemical entities, but instead draws them as plain bonds. The depiction also does not work with reaction SMILES.
• incorporate JavaGrins as an applet that outputs to a form element via JavaScript in Netscape Communicator.
• copy and paste from and to the form element and thereby access the system clipboard to a limited extent

Developing with Java Grins

JavaGrins can be incorporated as a SMILES generating component in any web page that needs a SMILES string. The SMILES string could be needed by a CGI component in a form, a JavaScript component, a plugin or another Java applet. We will discuss methods for enabling such access.

The LiveConnect API

The core of all such access is Netscape's LiveConnect API which enables JavaScript to Java communication. LiveConnect is a mechanism that enables various components on a web page to communicate with each other. The only requirement for this is that Java applets and plugins involved, if any, be LiveConnect enabled (JavaGrins is). With LiveConnect, both JavaScript and Java can communicate to exchange SMILES strings. JavaScript can furthermore communicate with other Java, CGI and plugin elements again via the LiveConnect API. Before proceeding further we urge the reader to peruse Chapter 5 of Netscape's JavaScript Guide. This document will clarify much of what follows. It will also clarify JavaScript and its ease of use. The interested reader is also recommended Chapter 38 in of the JavaScript Bible, 3rd edition by Danny Goodman (Publishers IDG Books Worldwide)

Security and Java

The central rule determining actions and directions (Java->JavaScript, JavaScript->CGI) is that due to security requirements, an action outside of an applet cannot cause that applet to connect to the network. For example, entering a SMILES in a CGI field can submit that SMILES to JavaGrins as the next SMILES to depict. However it cannot cause JavaGrins to connect to Daylight's DEPICT toolkit on the server to obtain a depiction of the molecule represented by that SMILES. That would be a security violation in Netscape's model. That activity, therefore has to be trigerred by a separate action from within the applet (in our case caused by invoking the SMILESToGrins submenu of the File Menu in JavaGrins.)

The Meat

As an example of how to use LiveConnect to communicate between say a CGI form and Java consider the html code which represents the JavaGrins example that comes shipped. The page basically has a CGI TextInput field and a JavaGrins applet that communicate. The CGI TextInput field is described by

    
    <form name=contentsForm METHOD=POST ACTION="mailto:ragu@daylight.com">
      Smiles:
      <input type=text
        name=smilesTextBoxInJavascript 
        value="    Loading... " 
        SIZE=20>
      <INPUT TYPE=text NAME="header" SIZE="15" VALUE="JavaGrins v.0.5">
      <br>
    </form>
    

We see that the form has a NAME attribute with a name of contentsForm and the input field has a NAME attribute with a name of smilesTextBoxInJavaScript. These names enable JavaScript to communicate and manipulate the form's value. As an example of how JavaScript can do this we present a JavaScript header function in the same document

      function setContentsForm(){
      document.contentsForm.smilesTextBoxInJavascript.value="c1ccccc1"
      }
    

In this case, while the document is invoked, it starts up and initializes the CGI field to say Loading JavaGrins while it loads up JavaGrins. After completion of loading, the header function setContentsForm() is invoked. This is enabled by the line

<BODY BGCOLOR="#FFFFFF" onLoad="setContentsForm()">
    

appearing after the header. This function sets the input field to contain the value c1cccc1 in our case. On startup Grins queries and finds this value in the input field and then depicts the corresponding molecule. So if you wished JavaGrins to come up with a different molecule like say progesterone at startup, you could replace c1cccc1 in the header function with the corresponding SMILES. Try it!

The above function sets the text input field's value to a desired value. With the LiveConnect API a Java applet can directly execute a JavaScript statement like the above from within Java. This is really a Java to JavaScript to CGI communication but enabled as a Java to CGI call. How does JavaGrins know what to set on obtaining a SMILES or what to query for in order to get a SMILES to depict? The name of the element whose value attribute can be set by JavaGrins is passed on to JavaGrins at startup. To clarify this, let us consider the HTML code invoking JavaGrins:

    <APPLET CODE="NetscapeApplet"
      CODEBASE="./"
      ARCHIVE="grins.jar"
      ALT="There is a Java Applet here. To view it you need a Java1.1-enabled browser."      
      ALIGN="CENTER"      
      HEIGHT=400
      WIDTH=400 
      MAYSCRIPT
      NAME="Grins">
      <PARAM NAME="ApplicationClass" value="daylight.services.AppLoader">
      <PARAM NAME="LiveConnectElement" value="document.contentsForm.smilesTextBoxInJavascript">
    </APPLET>

The parameter LiveConnectElement passed on to JavaGrins tells it the variable whose value property, it should set via JavaScript to the SMILES value. This is also the variable whose value JavaGrins should query in order to obtain a SMILES to depict.

Conclusion

Thus JavaGrins can communicate to any JavaScript accessible element in this manner. Elements accessible to JavaScript could be

• other Java applets
• JavaScript objects or elements
• CGI forms and their elements
• plugin elements (provided they are LiveConnect enabled)