Jmol Applet Documentation

The applet Jmol v6 is tested successfully with these browsers:

Errors were encountered with these browsers:

To embed the Jmol Applet in a web page, you need only one java archive file, JmolApplet.jar. All classes and data files are included in this file. Put this file in the directory on your webserver.

The name of the applet class is JmolApplet.

The Jmol applet can be embedded in html pages using the APPLET html tag:

      <applet code="JmolApplet" archive="JmolApplet.jar"
	width="350" height="350">
	<param name="load" value="caffeine.xyz">
	</applet>
	
    

CODE identifies the name of the class, in this case 'JmolApplet' or 'JmolApplet.class'. ARCHIVE identifies the name of the jar file where the classes for this applet are to be found. WIDTH and HEIGHT specify the dimensions of the applet within the html page in pixels.

The PARAM tags are used to pass parameters to the applet. The LOAD parameter specifies the URL of the molecule file which should be loaded.

The following is a slightly more complicated version with a few more options:

      <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	width="350" height="350" align="right">
	<param name="load"    value="molecules/caffeine.xyz">
	<param name="bgcolor" value="#DDDDFF">
	<param name="style"   value="quickdraw">
	<param name="label"   value="symbol">
	<param name="script"  value="move 0 0 360 0 0 0 0 0 5">
	<param name="wireframeRotation" value="true">
	<param name="perspectiveDepth"  value="false">
        </applet>
        
    

In this case the applet is given a name so that it can be referenced from JavaScript code (applet="jmol"). The applet is aligned to the right side of the page so that text flows to the left (align="right"). Using additional parameters (<param name="*" value="*">) a molecule is loaded from a relative URL on the web server (molecules/caffeine.xyz), the background color is set to a light blue (#DDDDFF), the style is set so that shaded atoms/bonds are not used (quickdraw), atoms are labeled with their atomic symbol (symbol), a script is run which rotates 360 degrees around the z axis in 5 seconds, wireframeRotation is turned on so that all movements are done in wireframe mode, and perspective depth is turned off so that the molecule rendering is a flat projection to the screen with no size adjustment for atoms and bonds further away from the viewer.

The complete list of Jmol Applet parameters is as follows:

The script parameter allows you to specify a script of RasMol/Chime commands to be executed after the molecule file is loaded.

Multiple script commands must be separated by the semicolon (;) character.

The underlying technology that supports this is known as LiveConnect. The LiveConnect layer provides the data and method conversion interface between the JavaScript world and the Java world.

Netscape and Internet Explorer have both supported LiveConnect for some time.

The Konqueror browser does not yet support LiveConnect.

Unfortunately, the news is not good for Macintosh OS X. Internet Explorer does not support LiveConnect. Neither does Safari (which is based upon Konqueror). (I have not yet checked Netscape on OS X.)

In order to reference an applet on an HTML page the applet must be given a name. We recommend that you use the name 'jmol' as in:

      <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	width="350" height="350">
	<param name="load" value="caffeine.xyz">
	</applet>
	
    

If you would like to have multiple instances of the applet on a single page then you should give them unique names.

With some browser versions you can sneak by without starting object references with 'document'. However, this does not work with many browsers. Therefore, we strongly recommend that you start all your references with 'document'.

Therefore, assuming you have named your applet 'jmol', all your references to the applet will start with 'document.jmol'. JavaScript method references in this documentation will use this notation.

Within a web page, there are several ways to invoke a JavaScript method based upon user events. One method is to use the 'javascript:' protocol in an href, as in:

      <a href="javascript:document.jmol.load('dna.xyz')">
	Load DNA molecule
      </a>
      
    

Another method is to use explicit JavaScript event tags, as in:

      <form name="myform">
	<input type="button" value="Rotate X 90"
	  onClick="document.jmol.script('rotate x 90')">
	<input type="button" value="Rotate Y 90"
	  onClick="document.jmol.script('rotate y 90')">
	<input type="button" value="Rotate Z 90"
	  onClick="document.jmol.script('rotate Z 90')">
      </form>
      
    

For further information on JavaScript programming we recommend that you search for JavaScript development resources on the web or at your nearest technical bookstore.

To get things to run on an installed base of older Netscape and IE browsers you may want to consider looking for 'old' documentation rather than 'up to date' documentation. One good reference source is http://developer.netscape.com/docs/manuals/js/client/jsguide/index.html

Jmol implements most of the scripting language found in the RasMol molecular visualization tool. For more detailed documentation on RasMol scripting see http://www.openrasmol.org

MDL extended the RasMol scripting language for use in their Chime plug-in. Jmol implements some of these script language extensions. For more detailed information on Chime and Chime/RasMol extensions see http://www.mdlchime.com/chime

For a complete listing of the RasMol/Chime scripting commands which are implemented in Jmol see the Jmol Guide. This listing gives brief descriptions of the commands.

The RasMol commands which are currently not implemented in Jmol are generally those associated with protein visualization: ribbons, strands, etc. In addition, the Jmol rendering engine does not currently handle intersecting spheres. So if you make the atom sizes large you will get disappointing results.

There are two methods of defining a script to be run by the applet

In either of these cases you can

In general, the first of these methods is only acceptable for short scripts. For longer scripts it is probably better to store the script files on the server and run them indirectly through the 'script' command.

All of the following examples load the molecule caffeine.xyz. Various ways of invoking scripts are demonstrated

A short script included as an applet parameter which is executed as soon as the applet is loaded.

      <html>
	<title>Example 1</title>
	<body>
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	    width="350" height="350">
	    <param name="load"   value="caffeine.xyz">
	    <param name="script" value="rotate x 90 ; background yellow">
	  </applet>
	</body>
      </html>
      
    

In this example, the script command is used to execute a longer script which is stored in the scripts subdirectory on the web server.

      <html>
	<title>Example 2</title>
	<body>
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	    width="350" height="350">
	    <param name="load"   value="caffeine.xyz">
	    <param name="script" value="script scripts/myLongScript.txt">
	  </applet>
	</body>
      </html>
      
    

This example uses onLoad to execute JavaScript which, in turn, drives the applet.

      <html>
	<title>Example 3</title>
        <body onLoad="document.jmol.script('select carbon; color green')">
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	    width="350" height="350">
	    <param name="load"   value="caffeine.xyz">
	  </applet>
	</body>
      </html>
      
    

Essentially the same thing, but loading a script off of the web server.

      <html>
	<title>Example 4</title>
	<body onLoad="document.jmol.script('script scripts/myLongScript.txt')">
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	    width="350" height="350">
	    <param name="load"   value="caffeine.xyz">
	  </applet>
	</body>
      </html>
      
    

Calling a javascript function which controls the script.

      <html>
	<title>Example 5</title>
	<script>
	  function runMyScript() {
	    document.jmol.script('move 0 0 360 0 0 0 0 0 4');
	  }
	</script>
	<body onLoad="runMyScript()">
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	    width="350" height="350">
	    <param name="load"   value="caffeine.xyz">
	  </applet>
	</body>
      </html>
      
    

Using buttons to call javascript methods, each of which is running a jmol script.

      <html>
	<title>Example 6</title>
	<script>
	  function rotateX() {
	    document.jmol.script('move 360 0 0 0 0 0 0 0 4');
	  }
	  function rotateY() {
	    document.jmol.script('move 0 360 0 0 0 0 0 0 4');
	  }
	  function rotateZ() {
	    document.jmol.script('move 0 0 360 0 0 0 0 0 4');
	  }
	</script>
	<body>
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
	    width="350" height="350">
	    <param name="load"   value="caffeine.xyz">
	  </applet>
	  <form>
	    <input type="button" value="rotate x" onClick="rotateX()"/>
	    <input type="button" value="rotate y" onClick="rotateY()"/>
	    <input type="button" value="rotate z" onClick="rotateZ()"/>
	  </form>
	</body>
      </html>
      
    

Using buttons to call javascript methods, each of which is driving a jmol animate script

    <html>
      <title>Example 7</title>
        <script>
	  function play(script) {
	    document.jmol.script(script);
	  }
	</script>
	<body>
	  <applet name="jmol" code="JmolApplet" archive="JmolApplet.jar"
                  width="350" height="350">
            <param name="load"   value="models/SN1_reaction.xyz">
          </applet>
          <form>
            <input type="button" value="next"
	           onClick="play('animate next')">
            <input type="button" value="prev"
	           onClick="play('animate prev')">
            <input type="button" value="rewind"
	           onClick="play('animate rewind')">
            <input type="button" value="play"
	           onClick="play('animate play')">
            <input type="button" value="revplay"
	           onClick="play('animate revplay')">
            <br>
            <input type="button" value="repeated with 2 second delay"
                   onClick="play('animate play; loop 2')">
            <br>
            <input type="button" value="repeated no delay"
                   onClick="play('animate play; loop 0')">
            <br>
            <input type="button" value="forward and reverse"
                   onClick="play('animate play; animate revplay; loop 0')">
          </form>
        </body>
      </html>