Jmol JavaScript Object

The Jmol JavaScript Object ("Jmol-JSO") is a set of JavaScript functions and utilities refactored and reorganized into a single JavaScript object. It supersedes the former Jmol.js JavaScript library, allowing a cleaner, more efficient way to interact with the Jmol applet on a web page, and abstracting the visualization of a molecular model so that the applet can be seamlessly replaced by an image or a third-party non-Java visualization resource (using WebGL and/or HTML5) depending on client's platform resources.

Using Jmol-JSO, a web page developer can target Java-challenged (iPad, iPhone) and Applet-challenged (Android) platforms but still implement Jmol on traditional platforms. Compromises will have to be made, because no other resource has the scripting power of Jmol. However, the wide variety of options available allows a subset of Jmol functionality on all such devices, and there should be no need to ever see a message "Sorry, you don't have Java installed...."

Jmol-JSO also allows easy access to public databases such as the RCSB PDB database, the National Cancer Institute CACTVS server, and PubChem, even when the Jmol Java applet is not available because of a user's platform.

In addition, Jmol-JSO allows easy interaction with the JSpecView applet (for spectroscopy) and the JME applet (for 2D drawing input) on a web page. Thus, 3D models can be tied to IR, NMR, UV/VIS, GC, and GC/MS spectra (using the JCAMP-DX Version 6 standard), 3D models can be embedded in JCAMP-DX files (see Jmol-JSpecView-specs.pdf), and 3D models can be introduce by a page visitor using simple chemical drawing.

Jmol-JSO is fully compatible with jQuery, creating the single global Jmol object. The library has been W3C and XHTML validated.

Installation

JmolJSO requires a small suite of JavaScript libraries that replace Jmol.js. However, the Java files necessary are the same:

• JmolApplet.jar or JmolAppletSigned.jar or JmolApplet0*.jar or JmolAppletSigned0*.jar

(That is, a set of files, where the * stands for several suffixes. You may need to read about signed vs. unsigned applet if you are unfamiliar with the Jmol jar files.)

Note that Java scurity policy imposes limitations on the folder location of files.

The basic suite of JavaScript libraries include these four:

• JmolCore.js (required)
• JmolApplet.js (required)
• JmolControls.js (optional -- required if any buttons or links or other input methods will be used)
• JmolApi.js (required)

However, AJAX access (by the unsigned applet or non-Java resources) to cross-domain resources such as public databases also requires jQuery.min.js and jQuery.iecors.js (loaded prior to JmolCore.js), and use of ChemDoodle, GLmol, JSpecView, or JME requires additional libraries.

Initialization

Note that JavaScript libraries not starting with "Jmol" may not be included in the Jmol distribution. Files can be found at chemapps.stolaf.edu/jmol and associated subdirectories. These include:

• jQuery.min.js The jQuery JavaScript library allowing the unsigned applet and non-Jmol options cross-domain access to public databases for all browsers other than MSIE.
• jQuery.iecors.js An extension of jQuery allowing the unsigned applet and non-Jmol options to have cross-domain access to public databases.
• ChemDoodleWeb.js ChemDoodle Web Components.
• gl-matrix-min.js Javascript Matrix and Vector library for High Performance WebGL apps; required for the ChemDoodle option only.
• mousewheel.js jQuery Mouse Wheel Plugin required for the ChemDoodle option only.
• GLmol.js GLmol - Molecular Viewer on WebGL/JavaScript.
• Three49custom.js A custom version of the WebGL 3D JavaScript library required for the GLmol option only and available at gitHub.

Basic

The web page at the very least should have the following in the head section (referencing files in appropriate directories if not the directory of the web page, as shown here):

<script type="text/javascript" src="JmolCore.js"></script>
<script type="text/javascript" src="JmolApplet.js"></script>
<script type="text/javascript" src="JmolControls.js"></script>
<script type="text/javascript" src="JmolApi.js"></script>


JmolControls.js may be omitted if no buttons, links, menus, or other user-interactive features are implemented on the page. All functions discussed below are found in JmolApi.js. The other files contain code that creates the various Jmol object prototypes and methods that are called from JmolApi.js.

Unsigned Jmol applet requiring access to public databases and all non-Java options

Web pages requiring the unsigned applet to access public databases, as well as all non-Jmol options, additionally require jQuery so that they can perform cross-browser or host-server AJAX calls:

<script type="text/javascript" src="jQuery.min.js"></script>
<script type="text/javascript" src="jQuery.iecors.js"></script>
<script type="text/javascript" src="JmolCore.js"></script>
<script type="text/javascript" src="JmolApplet.js"></script>
<script type="text/javascript" src="JmolControls.js"></script>
<script type="text/javascript" src="JmolApi.js"></script>


ChemDoodle option

Web pages utilizing ChemDoodle (either HTML5/WebGL or HTML5/non-WebGL versions) should have the following in their head section:

<script type="text/javascript" src="jQuery.min.js"></script>
<script type="text/javascript" src="jQuery.iecors.js"></script>
<script type="text/javascript" src="JmolCore.js"></script>
<script type="text/javascript" src="JmolApplet.js"></script>
<script type="text/javascript" src="JmolControls.js"></script>
<script type="text/javascript" src="JmolApi.js"></script>
<script type="text/javascript" src="gl-matrix-min.js"></script>
<script type="text/javascript" src="mousewheel.js"></script>
<script type="text/javascript" src="ChemDoodleWeb.js"></script>
<script type="text/javascript" src="JmolCD.js"></script>


GLmol option

<script type="text/javascript" src="jQuery.min.js"></script>
<script type="text/javascript" src="jQuery.iecors.js"></script>
<script type="text/javascript" src="JmolCore.js"></script>
<script type="text/javascript" src="JmolApplet.js"></script>
<script type="text/javascript" src="JmolControls.js"></script>
<script type="text/javascript" src="JmolApi.js"></script>
<script type="text/javascript" src="Three49custom.js"></script>
<script type="text/javascript" src="GLmol.js"></script>
<script type="text/javascript" src="JmolGLmol.js"></script>

Contributors

AngelHerraez, Hansonr, Hansonrstolaf, Cudo29, Ceroni, Ppillot