Jmol JavaScript Object

Jmol-JSO

The Jmol JavaScript Object (Jmol-JSO) is a set of JavaScript functions and utilities refactored and reorganized for Jmol 13.0 into a single JavaScript object (window.Jmol). The library JSmol.min.js supersedes the Jmol.js JavaScript library, allowing a cleaner, more efficient way to interact with Jmol on a web page, and abstracting the visualization of a molecular model so that the Java applet can be seamlessly replaced by a non-Java HTML5 canvas element (which might not even be Jmol) or even an image, depending on client platform's resources.

Jmol-JSO was initially developed by Bob Hanson and Paul Pillot in early 2012. It was folded into JSmol in late 2012.

Using Jmol-JSO, a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using a Jmol applet surrogate while still implementing Jmol/Java on traditional platforms. The wide variety of options available allows Jmol's 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 integrates facilities for direct, behind-the-scenes access to public databases such as the RCSB PDB database, the National Cancer Institute CACTVS server, and PubChem, even when the user's platform does not allow the Jmol Java applet.

In addition, Jmol-JSO allows easy interaction with

• the JSpecView Java applet, allowing one to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra (see more details)
• the JME Java applet, so 3D models can be generated by a page visitor using simple chemical 2D drawing (see more details)

Jmol-JSO is fully compatible with jQuery (although it requires its own customization of jQuery, JSmoljQuery.js). The library has been W3C and XHTML validated.

Main features of Jmol-JSO

Non-Java Options	Options for Java, HTML5/WebGL, HTML5-only, and image-only. Includes a variety of options, such as initial "deferred-applet" mode, where an initial image is displayed, with a click on the image or link on the page initiating applet/canvas 3D modeling, and "image+loading" mode, in which case the 3D model is loading behind the scenes while an initial image is displayed.
Library Files	Requires at a minimum, JSmol.min.js and j2s and/or java.
JavaScript Objects	Creates a single JavaScript Object, Jmol, which includes a set of functions and internal objects such as Jmol._Applet, Jmol._Image, and Jmol.controls.
JavaScript Prototypes	The object you create using Jmol.getApplet() is a JavaScript object that is a subclass of Jmol._Applet. When you use Jmol.getApplet(), you get a reference to a JavaScript object, not the Java applet/canvas itself. The applet or canvas is wrapped in a set of div elements, allowing a richer diversity of options.
AJAX	Jmol-JSO includes methods to easily access cross-platform resources using AJAX provided by jQuery.
REST services	Jmol-JSO lets you access keyword search results from RCSB -- for example, a list of all structures that reference caffeine.
Scripting	Jmol-JSO in conjunction with JSmol provides the same full complement of scripting that Jmol offers. Jmol-JSO accepts script commands immediately, before or during applet/canvas creation on the page, caching them until Jmol is ready to accept them.

JSmol

JSmol is the name for the HTML5 canvas version of the Jmol applet. JSmol opens up the use of Jmol to PC, Mac, and Linux systems without Java installed or with Java disabled as well as tablets and phones (both iOS and Android). No hardware-based graphics acceleration is used, allowing JSmol to run in any web browser that supports HTML5 standards. JSmol runs entirely in the client, needing no server technologies for most of its operation. (Reading binary files in some browsers and saving images and Jmol states in all browsers requires a server-side PHP script.)

JSmol was developed by Bob Hanson, Zhou Renjian, and Takanori Nakane.

JSmol allows rendering, scripting and interaction with the models just as Jmol does, since the source code is shared by both. Note that JSmol is not a different program than Jmol: it is Jmol, just compiled into JavaScript instead of Java (thanks to the Java2Script software).

Current limitations of JSmol

• Using local files (i.e. not in a web server) is not supported on some browsers due to their security policies (MSIE allows access to non-binary local files only; Opera allows no access to local files; Chrome allows access only when using a command-line flag).
• Opening binary files (e.g Spartan files, gzipped files, pngj files): they can be read, but must be identified as such in their file name (see below).
• Writing of jpg, png and pngj (png+zip) data is fully supported, but delivering it to a user may require a server-side piece. (See also Exporting an image for alternatives).
• The Jmol prompt command does not allow more than a simple JavaScript-like response in the HTML5 version.
• WebGL support is limited.

Reading binary files

Jmol/Java can open a file and then determine whether the file is binary or not. JSmol/JavaScript is different, because the AJAX transport mechanism is different for binary and nonbinary files. Thus, JSmol must determine whether a file is binary or not prior to its loading. JSmol does this by inspection of the file name. JSmol will switch to binary mode for files with any of the following in their file name: .gz .jpg .png .zip .jmol .smol .spartan .mrc .pse

These "extensions" can appear anywhere in a file name to trigger the binary access mode. So, for example, if you rename any file to include .bin anywhere in its name, that will instruct JSmol to read it as a binary file.

For binary file reading to be compatible with Chrome and MSIE, you will need to have a base64 server-side piece that will convert the binary data to BASE64 format. This is because only Firefox allows clean (reliable) synchronous binary file transfer. (And, so far, we have not figured out how to move all the file loading in Jmol to a fully asynchronous mode.) The demo pages use the jsmol.php script that is included in the JSmol distribution (see below), which does that and considerably more.

Converting pages from Jmol to JSmol

It is not hard to convert pages that currently use Jmol to use either the Java or the HTML5 versions of JSmol. The basic sequence includes:

• Switching from Jmol.js to JSmol.min.js
• Adding the java or j2s folders/directories to your website.
• Setting parameters in the Info variable.
• Modifying function calls from the format jmolXxxx(..., appletExtension) to Jmol.jmolXxxx(appletID, ...) (see below). Depending upon the magnitude of the problem, you may want to write a set of JavaScript functions that allow you to use all the methods on your page that you already use. For example, if you use the simplest from of jmolButton:

function jmolButton(script, label) {
  Jmol.jmolButton(myJmol, script, label)
}

Or you can just modify your function to the new format. All of the main methods found in Jmol.js (and more!) can be found in JSmolApi.js. You might consider taking this opportunity to find out how jQuery works, if you are not familiar with it, and work more with those functions.

Installation

As software evolves, it is possible that versions may differ in their compatibility; the Jmol team appreciates all feedback from web page developers in this regard and make every effort to keep the files up to date. Please file a bug report if you find a problem.

The most up-to-date version of JSmol can be found as St. Olaf. Full releases may be obtained at the JSmol Project page.

jsmol.zip contains these files and folders:

• Major files:
  • JSmol.min.js The only library that needs to be called explictly; it will take care of calling any of the other files as needed. (This includes a set of files minimized using the Google Closure Compiler)
    • JSmol.min.nojq.js An alternative version, to be used if you are not loading binary files and you already use jQuery on your page; this one bypasses JSmoljQuery.js.
  • jsmol.php A server-side PHP utility that allows a number of functions that can increase the platform and browser compatibility of JSmol. By default, JSmol will try to use a copy of this file at the St.Olaf server, but you need to put a copy in your own server in order to get full cross-platform compatibility in the following areas:
    • saving images (JPG, PNG) and binary Jmol states (JMOL, PNGJ, ZIP)
    • retrieving RCSB REST XML data services ("load =xxxxxxx?")
    • enabling cross-platform AJAX in MSIE (RCSB, NCI, PubChem)
    • reading binary files synchronously (as in the load command, or when using var x = load(...) in a Jmol script) in some browsers
  • JSmol.lite.js is a lightweight version of JSmol that will load very fast and offers minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at phones and systems with limited power, or as a quick first-look option that may be programmatically replaced by a full JSmol at user request.
    • JSmol.lite.jq.js An equivalent version but including jQuery.

• java The files for the JmolApplet, the same that have been used for Jmol in previous versions
  • 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.)

• js The suite of JavaScript libraries needed for building the Jmol-JSO object (but most of these files are already included in packed form within JSmol.min.js, see below):
  • j2sjmol.js Required interface to the Jmol and java classes (translated into JavaScript and compressed using the Google Closure Compiler.)
  • JSmol.js Primary JSmol library, with private methods for creating and interacting with canvases
  • JSmolApi.js All pubic user-intended interface functions
  • JSmolApplet.js Required applet prototypes for use with Java or HTML5
  • JSmolControls.js Required only if any buttons or links or other input methods will be used
  • JSmolCore.js Primary JSmol library, with private methods for file loading, primarily
  • JSmoljQuery.js A version of jQuery tweaked to allow synchronous binary file transfer and use with MSIE and Safari
  • JSmolJSV.js Needed only for using the JSpecView applet
  • JSmolGLmol.js Needed only when using the WebGL version of JSmol
  • JSmolThree.js Needed only when using the WebGL version of JSmol
• j2s The suite of JavaScript libraries needed for the HTML5 version of JSmol
• A few sample pages and files, included for your convenience but not required for functionality:
  • jsmol.htm, simple.htm, test2.htm, test3.htm , and cover.htm are demonstration/example pages
  • data Files used by the above demo pages
• make and test are for developers only. (The make directory includes the Google Closure Compiler used to create Jsmol.min.js.)

In summary:

• For pages that use HTML5-only JSmol, you just need JSmol.min.js and j2s (A total of 12.6 MB, but only those parts actually needed will be downloaded to the client computer).
• For pages that use only the Jmol Java applet, you just need JSmol.min.js and java (A total of 7.9 MB, but may be reduced to 2.2 MB for a single set of signed or unsigned applet files, of which only those parts actually needed will be downloaded to the client computer).
• js is only important if you want to use the (experimental, not fully functional) WebGL version of JSmol. Specifically, you need js/JSmolGLmol.js and js/JSmolThree.js (which are not minimized), since those two libraries are not included in JSmol.min.js.

Initialization

Loading the library

The web page should have the following in the head section (pointing to appropriate paths if not the same folder as the web page as shown here):

<script type="text/javascript" src="JSmol.min.js"></script>

Please note that there may be restrictions on the folder locations where you can put files for the libraries (js), the page (html), the models and scripts. This is imposed by browser security policies (related to both Java security and AJAX calls in JavaScript) and usually applies only to situations where you are using the pages from local disk (as opposed to a web server).

Successful file access by either the signed or unsigned Java applet or the HTML5 version of Jmol/JSmol depends upon whether the page is loaded using "file:" or "http:"

unsigned applet

http: .jar files must be located in the same folder as data files or in a folder above this.

file: same

signed applet

http: no restrictions

file: same as unsigned applet

HTML5 JSmol

http: all files should be on the host server or on a server set up to deliver cross-domain AJAX using the "Access-Control-Allow-Origin: *" header.

file: all files should be on the local machine within or under the folder containing the .html page.

All this needs confirmation. See also Java security policy which applies to the Java applet.

Optional components

• Integration with JME, a Java-based editor to draw 2D chemical structures (Peter Ertl's Java Molecular Editor)
• Integration with JSpecView, a Java viewer for spectral data.
• GLmol option to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems) (does not use Java)
• ChemDoodle option to render the 3D model using ChemDoodle (does not use Java)

Setting parameters

All of the initialization parameters supported in Jmol.js can be implemented in Jmol-JSO. However, the method of indicating variables is different. The essential call to create an applet or an alternative non-Java viewer is simply:

Jmol.getApplet("myJmol", Info)

This will create a myJmol global variable that holds the Jmol JavaScript object and is also the unique ID for that object in all functions and methods described below.

Note that myJmol and Info are user-defined variables and may hence have any name you wish. myJmol becomes in fact the identifier of the particular JmolApplet that is being created. You may wish to have two applets in your page and call them e.g. jmolA and jmolB, and use for them the same set of parameters Info, or use two different sets named e.g. InfoA and InfoB. To the contrary, Jmol (right after the equal sign) must be written as such, since it is the internal name and identification of the unique Jmol-JSO constructor.

Info is an associative array (a set of key/value pairs) indicating all the desired characteristics of the applet. The principal keys and their default values are given below:

var Info = {
  addSelectionOptions: false,
  color: "#FFFFFF",
  debug: false,
  defaultModel: "",
  height: 300,
  j2sPath: "j2s",              // HTML5 only
  isSigned: false,             // Java only
  jarFile: "JmolApplet0.jar",  // Java only
  jarPath: ".",                // Java only
  memoryLimit: 512,            // Java only
  readyFunction: null,
  script: null,
  serverURL: "http://chemapps.stolaf.edu/jmol/jsmol/jsmol.php",  // Example only!
  src: null,
  use: "Java noWebGL noHTML5 noImage",  // Autoswitching (not recommended)
  width: 300
};	 

Detailed explanation of the parameters of the Info variable.

Functions for creation or display of Jmol Objects

The following functions all relate to applet creation or display. All of them must be applied to the unique Jmol object (this name is literal, cannot be changed) --see syntax and examples below.

Jmol.getApplet

Definition: Jmol.getApplet = function(id, Info, checkOnly)

This function creates the JavaScript Object that keeps track of the Jmol applet (or the JSmol surrogate if a non-Java option is active). For example:

Jmol.getApplet("myJmol", Info);

A myJmol variable will be defined that holds the Jmol object, and the object will be inserted in the page (unless Jmol.setDocument() has been set false, see below).

checkOnly is an optional true/false flag that allows, when set true, to get a JavaScript Object that can be checked to see what type of Jmol object would be created on this particular platform -- a signed Java applet, an unsigned Java applet, a JSmol canvas, an image, a webGL canvas, etc.

Jmol.getAppletHtml

Definition: Jmol.getAppletHtml = function(id)

Useful for inserting the applet code into the page, in the case when it was generated and stored in a variable (id) after Jmol.setDocument(0). It is particularly useful within the jQuery $(document).ready function. For example:

$(document).ready(function(){
  Jmol.setDocument(0);
  Info.deferApplet = false;
  Info.deferUncover = true;
  Jmol.getApplet("jmol1", Info)    
  $("#appletplace1").html(Jmol.getAppletHtml(jmol1));
  Info.deferApplet = true;
  Info.deferUncover = true;
  Jmol.getApplet("jmol2", Info)    
  $("#appletplace2").html(Jmol.getAppletHtml(jmol2));
});

Jmol.getVersion

Definition: Jmol.getVersion = function()

This function returns the version of Jmol-JSO, like Jmol-JSO 13.0.

Example:

var t = Jmol.getVersion(myJmol);
alert(t);

Jmol.resizeApplet

Definition: Jmol.resizeApplet = function(applet,size)

(Untested in the HTML5 version of JSmol.) Used to change the dimensions of the specified applet.

size: a value or a pair of width/height values in an array, either expressed in pixels or as percent.

Examples:

Jmol.resizeApplet(myJmol, 400);
Jmol.resizeApplet(myJmol, [400,700]);
Jmol.resizeApplet(myJmol, "100%");
Jmol.resizeApplet(myJmol, ["50%","60%"]);

Jmol.setAppletSync

Definition: Jmol.setAppletSync = function(applets, commands, isJmolJSV)

Jmol.setDocument

Definition: Jmol.setDocument = function(doc)

doc is the target html context where the Jmol Object must be created.

If using Jmol.setDocument(false) or Jmol.setDocument(0), the Jmol Object may be later inserted using Jmol.getAppletHtml(). What happens is that the HTML code for the object is put into the internal applet._code variable and not written to the page. Then you can still refer to the applet, but place it on the page after the controls are made, or inject ot into the page upon some user action.

Example:

Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
document.getElementById('someContainer').innerHTML = Jmol.getAppletHtml(myJmol);

or, using jQuery syntax;

Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
$("#someContainer").html(Jmol.getAppletHtml(myJmol));

For some situations this may be equivalent to a simpler alternative: Just define the applet variable like var myJmol = "myJmol" and then, "myJmol" will suffice when providing any options or creating buttons and controls. Finally, use myJmol = Jmol.getApplet(myJmol,....) and the Object will work.

Jmol.setGrabberOptions

Definition: Jmol.setGrabberOptions = function(options)

Allows to customize the items offered in the drop-down menu that fetches molecules from databases, when using addSelectionOptions:true. Example:

Jmol.setGrabberOptions([
  ["$", "small molecules at NCI"],
  [":", "small molecules at PubChem"],
  ["==", "ligands at PDB"],
  ["=", "macromolecules at PDB"]
])

The first value in each element is the JmolScript prefix to direct the request to the database (this cannot be customized). The second value is the text that is displayed in the drop-down menu in the page, below the Jmol object.

Jmol.showInfo

Definition: Jmol.showInfo = function(applet, tf)

This displays or hides the information panel (which holds the log console, or maybe an associated JME applet). By default, that panel is located in the same position as the Jmol viewer, so displaying Info will hide Jmol and vice versa.

The tf parameter is a true or false flag.

Jmol.setInfo

Definition: Jmol.setInfo = function(applet, info, isShown)

Sets the information div for the applet to be info (HTML) and optionally displays it.

Jmol.setXHTML

Definition: Jmol.setXHTML = function(id)

Indicates the DOM node id to append HTML to for an XHTML page when creating page elements. Largely untested.

Functions for creating controls

These Jmol functions create elements of the page that the page visitor can use to interact with the applet or applet surrogate. Again, all these functions must be applied to the unique Jmol object (this name is literal, cannot be changed) --see syntax and examples below.

The first parameter for nearly all of these functions, appletOrId, must be a reference to the applet that will receive action of the control. Such reference is either the JSO object itself or its name-id (e.g. "myJmol" in the examples above).

In the following descriptions, a colored italic font is used for parameters that are optional.

Jmol.jmolButton

Inserts in the page a button with a text label.

Definition: Jmol.jmolButton(appletOrId, script, label, id, title)

Example:

var myInfo = {
  color: "#DDDDFF",
  script: "load myMolecule.mol;",
  height: 300,
  width: 300
};
Jmol.getApplet("myJmol", myInfo);
Jmol.jmolButton(myJmol,"spacefill on", "display as vdW spheres");

script is run when the button is pressed. As a special syntax (valid for any other controls as well as the button described here), instead of a Jmol script you can run a JavaScript function that you have defined, by providing this in place of the script: [funcName, param1, param2, param3...] The function must be defined in this way:

function funcName(btn, obj, target) {
    // Entire array object is provided as 2nd argument.
    var param1 = obj[1];
    var param2 = obj[2];
    var param3 = obj[3];
    // JavaScript to execute here.
    ....
}

label is the text in the button; if not specified, it defaults to the first 32 characters of the script.

id (optional) will be set as both the HTML id and HTML name. It will default to jmolButton0, jmolButton1, etc.

Advanced:

In addition, the button will be included in a <span> element that will have an HTML id of "span_" plus the given id, and an HTML title of the given title.

Browsers will hence show title as a tooltip when mouse pointer stays over the button.

Jmol.jmolCheckbox

Definition: Jmol.jmolCheckbox(appletOrId, scriptWhenChecked, scriptWhenUnchecked, labelHtml, isChecked, id, title)

Jmol.jmolCommandInput

Definition: Jmol.jmolCommandInput(appletOrId, label, size, id, title)

Jmol.jmolLink

Definition: Jmol.jmolLink(appletOrId, script, text, id, title)

script is run when the user clicks on the link.

text is written to the page as a link. If it is not specified, it defaults to the first 32 characters of script.

id will be set as both the HTML id and HTML name. It will default to jmolLink0, jmolLink1, etc.

Advanced:

In addition, the link text will be included in a <span> element that will have an HTML id of "span_" plus the given id, and an HTML title of the given title.

Browsers will hence show title as a tooltip when mouse pointer stays over the link.

Jmol.jmolMenu

Definition: Jmol.jmolMenu(appletOrId, arrayOfMenuItems, size, id, title)

Jmol.jmolRadio

Definition: Jmol.jmolRadio(appletOrId, script, labelHtml, isChecked, separatorHtml, groupName, id, title)

Jmol.jmolRadioGroup

Definition: Jmol.jmolRadioGroup(appletOrId, arrayOfRadioButtons, separatorHtml, groupName, id, title)

Jmol.setCheckboxGroup

Definition: Jmol.setCheckboxGroup(chkMaster,chkBox)

Functions that insert HTML

These simple commands just deliver HTML to the page. They are merely convenience functions for use from within the body so as not to have to continually switch in and out of script tags.

Again, all these functions must be applied to the unique Jmol object (this name is literal, cannot be changed) --see syntax and examples below.

Much better practice is to do all control creation in the header of the page, from within jQuery's $(document).ready() function, using Jmol.setDocument(0), appending the HTML to a growing string using the control-specific functions, then setting the code in a predefined div element using the jQuery $('#divId').html() function.

Jmol.jmolBr

Inserts a soft line break. Its only use is:

Jmol.jmolBr()

Jmol.jmolHtml

Allows to insert in the page any HTML code you may wish. Example:

Jmol.jmolHtml(' <b style="color:red">H<sub>2</sub>O</b> ')

Functions that set CSS rules

These functions, called prior to the creation of the associated object(s), allow the page designer to add specific attributes (usually, but not necessarily CSS style attributes) to the HTML tag(s) that will be created later. This allows setting one or more common style attributes for, for example, all buttons in a certain cell of a table, or all radio buttons of a certain group. Either a class name or an attribute can be given. For example:

  Jmol.setButtonCss(null, "style='width:160px'");

Again, all these functions must be applied to the unique Jmol object (this name is literal, cannot be changed) --see syntax and examples below.

Jmol.setAppletCss

Definition: Jmol.setAppletCss = function(cssClass, text)

Jmol.setButtonCss

Definition: Jmol.setButtonCss = function(cssClass, text)

Jmol.setCheckboxCss

Definition: Jmol.setCheckboxCss = function(cssClass, text)

Jmol.setLinkCss

Definition: Jmol.setLinkCss = function(cssClass, text)

Jmol.setMenuCss

Definition: Jmol.setMenuCss = function(cssClass, text)

Jmol.setRadioCss

Definition: Jmol.setRadioCss = function(cssClass, text)

Other public methods

All these functions must be applied to the unique Jmol object (this name is literal, cannot be changed) --see syntax and examples below.

(TO-DO -- just transfer text with slight modification from jslibrary)

Definitions:

Jmol.evaluate = function(applet,molecularMath) 
Jmol.getInfo = function(applet) 
Jmol.getPropertyAsArray = function(applet,sKey,sValue)
Jmol.getPropertyAsJavaObject = function(applet,sKey,sValue)
Jmol.getPropertyAsJSON = function(applet,sKey,sValue) 
Jmol.getPropertyAsString = function(applet,sKey,sValue)
Jmol.getStatus = function(applet,strStatus) 
Jmol.loadFile = function(applet, fileName, params)
Jmol.restoreOrientation = function(applet,id) 
Jmol.restoreOrientationDelayed = function(applet,id,delay)
Jmol.saveOrientation = function(applet,id) 
Jmol.say = function(msg) 
Jmol.script = function(applet, script) 
Jmol.scriptEcho = function(applet, script) 
Jmol.scriptMessage = function(applet, script) 
Jmol.scriptWait = function(applet, script) 
Jmol.scriptWaitAsArray = function(applet, script) 
Jmol.scriptWaitOutput = function(applet, script)  
Jmol.search = function(applet, query, script) 

Methods specific to optional components

• Methods specific to the JME applet
• Methods specific to the JSpecView applet

Contributors

AngelHerraez, Hansonr, Hansonrstolaf, Cudo29, Ceroni, Ppillot