Difference between revisions of "Jmol JavaScript Object"

From Jmol
Jump to navigation Jump to search
(updating and rearranging content)
(installation instructions moved to separate page and updated to Jmol 16)
 
(166 intermediate revisions by 4 users not shown)
Line 1: Line 1:
''This page is under construction.''
+
{{Lang:Jmol JavaScript Object}}
  
WORK IN PROGRESS -- REMODELLING AND REWRITING OF Jmol-JSO + JSmol PAGE
+
== JSmol, the Jmol JavaScript Object ==
-----------------------
+
<div style="float:right; margin-left:1em;">
 +
__TOC__
 +
</div>
 +
<div style="float:left;">
 +
[[Image:JSmol_logo13.png]]
 +
</div>
  
== Jmol-JSO ==
+
The heart of JSmol is the Jmol JavaScript object, (<code>window.Jmol</code>), which includes a set of JavaScript functions and utilities.  The initial Jmol object was developed by Bob Hanson and Paul Pillot in early 2012. It was folded into '''JSmol''' later that year. The library {{file| JSmol.min.js}} provides this object and supersedes the Jmol.js JavaScript library formerly used exclusively with the Jmol Java applet, 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 and selectively replaced by a non-Java HTML5 canvas element (which might not even be Jmol).
  
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. It supersedes the former [{{Website}}jslibrary/ 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 a non-Java visualization resource, like '''JSmol''' or a third-party resource (using WebGL and/or HTML5), or even an image, depending on client's platform resources.  
+
Using '''JSmol''', a web page developer can target most web browsers that no longer support Java applets, using '''a Jmol applet surrogate''', while still implementing the Jmol Java applet on compatible platforms.  
  
Using '''Jmol-JSO''', a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using '''a Jmol applet surrogate''' (such as '''[[JSmol]]''', GLmol, ChemDoodle, or just an image) while still implementing JmolApplet on traditional platforms. Compromises will have to be made, because other resources do not have the scripting power of Jmol and JSmol. 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...."
+
'''JSmol''' also integrates facilities for direct, behind-the-scenes access to public databases such as the [https://rcsb.org RCSB PDB database], the [https://cactus.nci.nih.gov/ National Cancer Institute CACTVS server], and [https://pubchem.ncbi.nlm.nih.gov/ PubChem].
  
'''Jmol-JSO''' also integrates facilities for direct, behind-the-scenes access to public databases such as the [http://rcsb.org RCSB PDB database], the [http://cactus.nci.nih.gov/ National Cancer Institute CACTVS server], and [http://pubchem.ncbi.nlm.nih.gov/ PubChem], even when the user's platform does not allow the Jmol Java applet.
+
In addition, '''JSmol''' allows easy interaction with
 +
* the '''JSpecView HTML5 object''', allowing one to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra (see [[Jmol_JavaScript_Object/JSV|more details]])
 +
* the '''JSME HTML5 object''', so 3D models can be generated by a page visitor using simple chemical 2D drawing (see [[Jmol_JavaScript_Object/JME|more details]])
  
In addition, '''Jmol-JSO''' allows easy interaction with
+
'''JSmol''' is fully compatible with [http://jquery.com jQuery] 1.9 or 1.10. (jQuery 2.0 does not and for reasons of principle reportedly will never support MSIE running locally using file://, so if you do not need to run your page in MSIE in a local environment, that should be fine. There is a fix for this, however, if you must do that. In that case you must hack jQuery a bit.) The library has been W3C and XHTML validated.
* the '''JSpecView applet''', allowing to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra (see [[Jmol_JavaScript_Object/JSV|more details]])
 
* the '''JME applet''', so 3D models can be generated by a page visitor using simple chemical 2D drawing.
 
  
'''Jmol-JSO''' is fully compatible with [http://jquery.com jQuery], creating the single global <code>Jmol</code> object. The library has been W3C and XHTML validated.
+
===Main features of JSmol ===
 
 
===Representative differences with Jmol.js===
 
 
<table class="wikitable">
 
<table class="wikitable">
 
<tr>
 
<tr>
<th>Aspect</th><th>Jmol-JSO</th><th>Jmol.js</th>
+
<th>Non-Java options</th><td>Options for HTML5-only and optionally Java and HTML5/WebGL. 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.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<th>Non-Java Options</th><td>Automatically switches to non-Java surrogates.</td><td>No such capability.</td>
+
<th>Library files</th>
 +
<td>Requires at a minimum {{file|JSmol.min.js}} as well as {{folder|j2s}}; for internationalized interface, also {{folder|idioma}}. Also optionally {{folder|java}}.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<th>Library Files</th>
+
<th>JavaScript objects</th>
<td>Requires at a minimum, {{file|JmolCore.js}}, {{file|JmolApplet.js}}, and {{file|JmolApi.js}}.</td>
+
<td>Creates a single JavaScript object, <code>Jmol</code>, which includes a set of functions and internal objects such as <code>Jmol._Applet</code>, <code>Jmol._Image</code>, and <code>Jmol.controls</code>.</td>
<td>Requires only {{file|Jmol.js}}</td>
 
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<th>JavaScript Objects</th>
+
<th>JavaScript prototypes</th>
<td>Creates a single JavaScript Object, <code>Jmol</code>, which includes a set of functions and internal objects such as <code>Jmol._Applet</code>, <code>Jmol._Image</code>, and <code>Jmol.controls</code>.</td>
+
<td>The object you create using <code>Jmol.getApplet()</code> or <code>Jmol.getAppletHtml()</code> is a JavaScript object that is a subclass of <code>Jmol._Applet</code>. When you use <code>Jmol.getApplet()</code>, you get a reference to a JavaScript object, not the applet/canvas itself. The applet or canvas is wrapped in a set of <code>div</code> elements, allowing a richer diversity of options.</td>
<td>Creates the <code>_jmol</code> associative array, but only uses it to hold parameter and variable values.</td>
 
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<th>JavaScript Prototypes</th>
+
<th>AJAX</th>
<td>The object you create using <code>Jmol.getApplet()</code> is a JavaScript object that is a subclass of <code>Jmol._Applet</code> (generally). When you use <code>Jmol.getApplet()</code>, you get a reference to a JavaScript object, not the Java applet itself. This wrapper allows a richer diversity of interaction with the actual Java applet or its surrogate.</td>
+
<td>JSmol includes methods to easily access cross-platform resources using AJAX provided by jQuery.</td>
<td><code>jmolApplet()</code> creates the applet with a given id and name (such as "jmolApplet0"), but no JavaScript wrapper object for it.</td>
 
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<th>AJAX</th>
+
<th>REST services</th>
<td>Jmol-JSO includes methods to easily access cross-platform resources using AJAX provided by jQuery.</td>
+
<td>JSmol lets you access keyword search results from RCSB -- for example, a list of all structures that reference ''caffeine''.</td>
<td>No AJAX support.</td>
 
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
<th>Scripting</th>
 
<th>Scripting</th>
<td>Starts accepting script commands immediately, caching them until the Java applet is ready to accept them.</td>
+
<td>JSmol provides the same full complement of scripting that Jmol offers. JSmol accepts script commands immediately, before or during applet/canvas creation on the page, caching them until Jmol is ready to accept them.</td>
<td>Cannot accept script commands until the Java applet is fully initialized. (Requires some sort of applet-ready callback.)</td>
 
 
</tr>
 
</tr>
 
</table>
 
</table>
  
 
== JSmol ==
 
== JSmol ==
...
+
<div style="float:left;">
 +
[[Image:JSmol_logo13.png]]
 +
</div>
  
==Installation==
+
'''JSmol''' is the name for the HTML5 canvas version of the former Jmol applet. '''JSmol''' opens up the use of Jmol in PC, Mac, and Linux systems, tablets and phones (both iOS and Android) without the need for Java. 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 do require a server-side PHP script, commonly provided as {{file|php/jsmol.php}} &ndash;read details below.)
  
JmolJSO requires a suite of JavaScript libraries that replace Jmol.js. There are also a set of files that implement JSmol, the Javascript-only alternative to Jmol. Finally, there are the Java files for the classic JmolApplet, which remain the same.
+
'''JSmol''' was developed by Bob Hanson, Zhou Renjian, and Takanori Nakane.
  
The download contains these:
+
'''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 [http://java2script.sourceforge.net/ Java2Script] software).
  
* {{file|java}} folder: contains the files for the JmolApplet, the same that have been used for Jmol in previous versions
+
===Current limitations of JSmol ===
** {{file|JmolApplet.jar}} or {{file|JmolAppletSigned.jar}} or {{file|JmolApplet0*.jar}} or {{file|JmolAppletSigned0*.jar}}
+
* Using local files (i.e. not in a web server) is not supported on some browsers due to their security policies:
:: (That is, a set of files, where the * stands for several suffixes. You may need to read about [[Jmol_Applet#Unsigned_vs._Signed_Applet_.26_Data_Access|signed vs. unsigned applet]] if you are unfamiliar with the Jmol jar files.)
+
** Opera allows no access to local files.
:: Note that [[Troubleshooting/Applet#Java_security_errors|Java security policy]] imposes limitations on the folder location of files.  
+
** MSIE allows access to local files only if they are not binary.
* {{file|js}} folder: the suite of JavaScript libraries needed for JSO-Jmol
+
** Chrome allows access only when Chrome has been started using a special command-line flag (<code>chrome.exe --allow-file-access-from-files</code>).
** {{file|JSmol.js}}
+
** Firefox allows access only after setting a special <code>about:config</code> flag (<code>security.fileuri.strict_origin_policy = false</code>).
** {{file|JSmolCore.js}} (required)
+
* Opening binary files (e.g Spartan files, gzipped files, {{file|pngj}} files): they can be read but must be identified as such in their file name (see below).  
** {{file|JSmolApplet.js}} (required)
+
* Writing of {{file|jpg}}, {{file|png}} and {{file|pngj}} (png+zip) data is fully supported, but delivering it to a user may require a server-side piece. (See also [[Recycling_Corner#Exporting_an_image_from_the_applet|Exporting an image]] for alternatives).
** {{file|JSmolControls.js}} (optional -- required if any buttons or links or other input methods will be used)
+
* The Jmol <code>prompt</code> command does not allow more than a simple JavaScript-like response in the HTML5 version.
** {{file|JSmolApi.js}} (required)
+
* The [[Jmol_JavaScript_Object/WebGL|WebGL modality]] of JSmol has not been fully developed and feature support is limited.
** {{file|JSmolThree.js}}
 
** {{file|JSmolApi.js}}
 
  
 +
=== 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.
  
* {{file|JSmol.min.js}}
+
==== File names ====
* {{file|jsmol.php}} is a utility that allows some server-side operations (...more details to be included here...)
+
JSmol will determine whether a file is binary or not &mdash;before loading it&mdash; by inspection of the file name. JSmol will switch to binary mode for files with any of the following in their file name:
* {{file|jsmol.htm}}, {{file|simple.htm}}, {{file|test2.htm}} are demonstration/example pages
+
{{file|.bin}}
 +
{{file|.gz}}
 +
{{file|.zip}}
 +
{{file|.jpg}}
 +
{{file|.png}}
 +
{{file|.jmol}}
 +
{{file|.smol}}
 +
{{file|.spartan}}
 +
{{file|.mrc}}
 +
{{file|.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 <code>.bin</code> anywhere in its name, that will instruct JSmol to read it as a binary file.
  
 +
:''Advanced'': If you need a different extension to be read as binary, and cannot change the file names to include one of the default extensions, it is possible to extend the set using this code in your JavaScript after the Jmol object has being initialized: <code>Jmol._binaryTypes.push('.myExtension');</code>
  
 +
==== Browser behaviour ====
 +
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 <code>BASE64</code> 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.)
  
However, AJAX access (by the unsigned applet or non-Java resources) to cross-domain resources such as public databases also requires {{file|jQuery.min.js}} and {{file|jQuery.iecors.js}} (loaded prior to JmolCore.js), and use of ChemDoodle, GLmol, JSpecView, or JME requires additional libraries.
+
If your page visitors need to read binary files, place a copy of the {{file|jsmol.php}} file that is included in the JSmol distribution (see below) on your server and point to it using the [[Jmol_JavaScript_Object/Info#Files_and_paths|'''serverURL''' item of the Info array]].
 +
As an example, the [{{StOlaf}}jsmol/jsmol.htm demo pages] use this approach.
  
==Initialization==
+
For that to work, your server must support PHP. Otherwise, you might "borrow" by pointing to the {{file|jsmol.php}} file in another server that can run PHP (please, ask the owner of that server).
  
Note that JavaScript libraries not starting with "Jmol" may not be included in the Jmol distribution. Files can be found at [http://chemapps.stolaf.edu/jmol chemapps.stolaf.edu/jmol] and associated subdirectories or at the links shown below. 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 at chemapps.stolaf.edu up to date. Please file a [http://sourceforge.net/tracker/?group_id=23629&atid=379133 bug report] if you find a problem. These libraries include:
+
In Chrome and also other browsers, you may overcome problems with loading '''''local''''' binary files by running pages through a local web server.
  
* {{file|jQuery.min.js}} The [http://jquery.com/ jQuery JavaScript library] allowing the unsigned applet and non-Jmol options cross-domain access to public databases for all browsers other than MSIE.
+
=== Converting legacy web pages to JSmol ===
* {{file|jQuery.iecors.js}} An [https://github.com/dkastner/jquery.iecors extension of jQuery] allowing the unsigned applet and non-Jmol options to have cross-domain access to public databases.
 
* {{file|ChemDoodleWeb.js}} [http://web.chemdoodle.com/ ChemDoodle Web Components].
 
* {{file|gl-matrix-min.js}} [https://github.com/toji/gl-matrix Javascript Matrix and Vector library for High Performance WebGL apps]; required for the ChemDoodle option only.
 
* {{file|mousewheel.js}} [https://github.com/brandonaaron/jquery-mousewheel/ jQuery Mouse Wheel Plugin] required for the ChemDoodle option only.
 
* {{file|GLmol.js}} [http://webglmol.sourceforge.jp/index-en.html GLmol - Molecular Viewer on WebGL/JavaScript].
 
* {{file|Three49custom.js}} A custom version of the [http://mrdoob.github.com/three.js/ WebGL 3D JavaScript library] required for the GLmol option only and available at [https://github.com/biochem-fan/GLmol/tree/master/src/js gitHub].
 
  
===Basic===
+
It is not hard to convert pages that used the Jmol Applet and the <code>Jmol.js</code> library to use the HTML5 versions of JSmol. See [[Jmol JavaScript Object/Legacy|more details]].
  
The web page at the very least should have the following in the <code>head</code> section (referencing files in appropriate directories if not the directory of the web page, as shown here):
+
==Installation==
 +
See [[Jmol JavaScript Object/Installation]]
  
<code>
+
==Initialization==
&lt;script type="text/javascript" src="JmolCore.js">&lt;/script><br />
+
=== Browser issues ===
&lt;script type="text/javascript" src="JmolApplet.js">&lt;/script><br />
+
JSmol makes strong use of the HTML5 features. Therefore, it is only compatible with modern web browsers. Specifically, ''Internet Explorer must be version 9 or higher''.
&lt;script type="text/javascript" src="JmolControls.js">&lt;/script><br />
 
&lt;script type="text/javascript" src="JmolApi.js">&lt;/script><br />
 
</code>
 
  
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.
+
In addition, it is important to use a doctype in the header of the html page. The recommended doctype is the simple one, associated to HTML5 standard, as the very first line of your html document.
  
===Unsigned Jmol applet requiring access to public databases and all non-Java options ===
+
Also, for full compatibility, particularly for the localization (language translations) of the JSmol pop-up menu, you should declare the charset as UTF-8 and save the html document (and all accessory files) using UTF-8 encoding (usually without [[wikipedia:Byte_order_mark#UTF-8|BOM]], but this needs further confirmation; recent versions of Firefox seem to have problems with non-BOM UTF-8 files, and UTF-8 with BOM looks like a better solution).
  
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:
+
Therefore your html documents should start as:
 +
<!DOCTYPE HTML>
 +
<html>
 +
<head>
 +
<meta charset="utf-8">
  
<code>
+
=== Loading the library ===
&lt;script type="text/javascript" src="jQuery.min.js">&lt;/script><br />
 
&lt;script type="text/javascript" src="jQuery.iecors.js">&lt;/script><br />
 
&lt;script type="text/javascript" src="JmolCore.js">&lt;/script><br />
 
&lt;script type="text/javascript" src="JmolApplet.js">&lt;/script><br />
 
&lt;script type="text/javascript" src="JmolControls.js">&lt;/script><br />
 
&lt;script type="text/javascript" src="JmolApi.js">&lt;/script><br />
 
</code>
 
  
=== Optional components ===
+
The web page should have the following in the <code>head</code> section (pointing to appropriate paths if not the same folder as the web page as shown here):
* [[Jmol_JavaScript_Object/JME|Integration with JME]], a Java-based editor to draw 2D chemical structures (Peter Ertl's Java Molecular Editor)
 
* [[Jmol_JavaScript_Object/JSV|Integration with JSpecView]], a Java viewer for spectral data.
 
* [[Jmol_JavaScript_Object/GLmol|GLmol option]] to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems) (does not use Java)
 
* [[Jmol_JavaScript_Object/ChemDoodle|ChemDoodle option]] to render the 3D model using ChemDoodle (does not use Java)
 
  
===Initialization parameters===
+
<code><script type="text/javascript" src="JSmol.min.js"></script></code>
  
All of the initialization parameters common to 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:
+
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).
  
<code>
+
: Successful file access by JSmol depends upon whether the page is loaded using "file:" or "http:"
myJmol = Jmol.getApplet("myJmol", Info)
+
:: <code>http:</code> 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.
</code>
+
:: <code>file:</code> all files should be on the local machine within or under the folder containing the {{file|.html}} page.
:Note that <tt>myJmol</tt> and <tt>Info</tt> are user-defined variables and may hence have any name you wish. <tt>myJmol</tt> 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. <tt>jmolA</tt> and <tt>jmolB</tt>, and use for them the same set of parameters <tt>Info</tt>, or use two different sets named e.g. <tt>InfoA</tt> and <tt>InfoB</tt>. To the contrary, <tt>Jmol</tt> (right after the equal sign) must be written as such, since it is the internal name and identification of the unique Jmol-JSO constructor.
+
: ''All this needs confirmation''. See also [[Troubleshooting/Applet#Java_security_errors|Java security policy]] which applies to the Java applet.  
  
:When you use this method, ALWAYS use the name of the variable being assigned to the JavaScript Object in quotes as the first parameter. This is important, because controls created in relation to the applet and callback functions from the Java applet need to incorporate the ID of the applet's JavaScript Object in order to work properly.
+
==== Lightweight JSmol ====
 +
There is an alternative version of Jmol object that, using the HTML5 canvas like JSmol, loads very fast while offering minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at smartphones and such systems with limited resources.  
  
<tt>Info</tt> is an associative array (a set of key/value pairs) indicating all the desired characteristics of the applet. For a full, up-to-date description of all of the '''Info''' options, see [{{SVN Trunk}}Jmol/appletweb/JmolApi.js JmolApi.js]. It is recommended that any page developer interested in utilizing Jmol extensively take a look at this file. The principal Info keys and their default values are given below:
+
For more details on how to use this, see [[Lightweight JSmol]].
  
<pre>
+
==== Optional components ====
var Info = {
+
* [[Jmol_JavaScript_Object/JME|Integration with JSME]], an editor to draw 2D chemical structures (Peter Ertl's JavaScript Molecular Editor)
  addSelectionOptions: false,
+
* [[Jmol_JavaScript_Object/JSV|Integration with JSpecView]], a viewer for spectral data.
  color: "#FFFFFF",
+
* [[Jmol_JavaScript_Object/WebGL|WebGL modality]] to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems)
  debug: false,
+
* [[Jmol_JavaScript_Object/ChemDoodle|ChemDoodle option]] to render the 3D model using ChemDoodle
  defaultModel: "",
 
  height: 300,
 
  isSigned: false,
 
  jarFile: "JmolApplet0.jar",
 
  jarPath: ".",
 
  memoryLimit: 512,
 
  readyFunction: null,
 
  script: null,
 
  serverURL: "http://chemapps.stolaf.edu/jmol/jmolcd.php",
 
  src: null,
 
  use: "Java noWebGL noHTML5 noImage",
 
  width: 300
 
};
 
</pre>
 
  
* '''Info.addSelectionOptions''' Set this value to <code>true</code> if you want to display, below the applet, a menu with options for loading structures from public databases.
+
=== Setting parameters ===
* '''Info.color'''  The background color of the applet, in any JmolScript-supported format: color name, decimal triplet <code>[r,g,b]</code> or hexadecimal <code>[xRRGGBB]</code>. Note that default is white (it is black in the classic Jmol.js method).
+
The essential and minimal call to create a JSmol object is simply:
* '''Info.debug'''  Set this value to <code>true</code> if you are having problems getting your page to show the applet or buttons.
 
* '''Info.defaultModel''' A model to be retrieved from a public database and displayed when the applet is loaded.
 
* '''Info.height'''  The size of the applet (or surrogate) in pixels or expressed as percent of its container height as a string in quotes: "100%". Note that for a percent to work, '''''all''''' surrounding HTML elements (including <code>body</code> and <code>html</code>) must explicitly implement the CSS attribute <code>style=height:...</code>.
 
* '''Info.isSigned'''  Make sure to change this to <code>true</code> if the file indicated for '''Info.jarFile''' is the signed applet.
 
* '''Info.jarFile'''  The file used, usually either <code>JmolApplet0.jar</code> (for faster incremental loading) or <code>JmolApplet.jar</code> (a single 2.5+ MB download), or the signed versions <code>JmolAppletSigned0.jar</code> and <code>JmolAppletSigned.jar</code>.
 
* '''Info.jarPath'''  The path to the applet files. Note that if the unsigned applet is used and the page is tested locally, then all model files must be in or under the folder indicated by this value, to satisfy Java security policy.
 
* '''Info.memoryLimit''' The maximum amount of memory allowed for the applet, in MB.
 
* '''Info.readyFunction''' The name of a JavaScript function to call when the applet has been created and is ready to receive commands (and also called when the applet is destroyed e.g. when the page is closed).
 
*: For example, with <code>Info.readyFunction: jmolIsReady</code> any of the following JavaScript function definitions could be used:
 
*: <code>jmolIsReady = function(theJmol) { document.title = theJmol._id + " is ready"; }</code>
 
*: <code>jmolIsReady = function() { alert('Welcome to Jmol!'); }</code>
 
*: <code>function jmolIsReady() { alert('Welcome to Jmol!'); }</code>
 
* '''Info.script''' A script to run when the applet has loaded. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to the applet as soon as the applet wrapper object has been created in JavaScript; there is no need to wait for Java applet initialization to have completed.
 
* '''Info.serverURL''' The URL of the server to be used for getting file data into non-JmolApplet options. This can be left as "http://chemapps.stolaf.edu/jmol/jmolcd.php", since that is a public site accessible to cross-domain AJAX calls, but it can perhaps better be installed on the user's host for better performance.
 
* '''Info.src''' Same as '''Info.script''', only included because it is the syntax commonly used for images.
 
* '''Info.use''' This string determines the various options to be tried (applet and surrogates) and the order in which to try them.
 
** The default setting of <code> Java noWebGL noHTML5 noImage </code> is the same as just <code> Java </code> by itself and indicates to just use Java (and display a message if Java is not enabled).
 
** A value of <code> Java Image </code> would allow PNGJ files to be displayed as images or simple file loading to be delivered as an image from a server if Java is not available.
 
** The value <code> Java HTML5 </code> would test for Java and then, if that is not available, use GLmol or HTML5-only ChemDoodle or JSmol (whichever is made available).
 
** The value <code> Java WebGL HTML5 Image </code> allows at least some model on all standard platforms.
 
: Note that Jmol-JSO cannot detect if the user has intentionally disabled Java in Microsoft Internet Explorer. Thus, MSIE users intentionally disabling Java will only have the Java option, and a message will be displayed that Java is not available.
 
* '''Info.width'''  The width of the applet in pixels or expressed as percent of its container width as a string in quotes: "100%". Note that for a percent to work, '''''all''''' surrounding HTML elements must explicitly implement the CSS attribute <code>style=width:...</code>.
 
  
In addition to these keys are a set of parameters that using Jmol.js could be set using the <code>jmolSetParameter()</code> or <code>jmolSetCallback()</code> functions. These are discussed in sets:
+
<code>Jmol.getApplet("myJmol")</code>
  
* '''Info.animframecallback'''
+
This will create a <tt>myJmol</tt> global variable in JavaScript that holds the JSmol object and is also the unique ID for that object in all functions and methods described below. ''Note that this simplest syntax will only work when the html file is located in the root JSmol folder.''
* '''Info.appletreadycallback'''
 
* '''Info.atommovedcallback'''
 
* '''Info.echocallback'''
 
* '''Info.evalcallback'''
 
* '''Info.hovercallback'''
 
* '''Info.loadstructcallback'''
 
* '''Info.messagecallback'''
 
* '''Info.pickcallback'''
 
* '''Info.measurecallback'''
 
* '''Info.minimizationcallback'''
 
* '''Info.resizecallback'''
 
* '''Info.scriptcallback'''
 
* '''Info.synccallback'''
 
  
These callbacks allow the page designer to get information about what is happening within the applet. The name of a JavaScript function, in single- or double-quotes should be given here if desired. Do not use <code>function() {....}</code> syntax.
+
However, in most situations you will want to customize some aspects, like the size of the object and the file paths. All of the initialization parameters can be specified.  
  
* '''Info.language'''
+
The regular call to create a JSmol object with specified characteristics is
This setting can be used to specify a language to be used in the JmolApplet interface (primarily for testing; the default language used in the applet is automatically detected from the system settings of the user's browser).
+
to define an <code>Info</code> variable, which is an associative array (a set of key+value pairs) that indicates all the desired characteristics of the JSmol object.
 +
The JSmol.min.js library will provide a default <code>Info</code> variable, so you only need to specify those keys which values you want to customize.
  
* '''Info.usecommandthread'''
+
Once <code>Info</code> has been defined, you create and insert the JSmol object in the page using this:
The signed Jmol applet generally runs commands by passing them to a command thread that is established when the applet is created, while the unsigned applet does not. You can change this behavior if you are observing Java security issues. Otherwise, it should not be adjusted.
 
  
* '''Info.boxbgcolor'''
+
<code>'''Jmol'''.getApplet("myJmol", Info)</code>
* '''Info.boxfgcolor'''
 
* '''Info.boxmessage'''
 
* '''Info.progressbar'''
 
* '''Info.progresscolor'''
 
These five values generally should not be adjusted.
 
  
== Applet Creation or Display Functions ==
+
:Note that <tt>myJmol</tt> and <tt>Info</tt> are user-defined variables and may hence have any name you wish. <tt>myJmol</tt> becomes in fact the identifier of the particular JSmol object that is being created. You may wish to have two JSmols in your page and call them e.g. <tt>jmolA</tt> and <tt>jmolB</tt>, and use for them the same set of parameters <tt>Info</tt>, or use two different sets named e.g. <tt>InfoA</tt> and <tt>InfoB</tt>. In contrast, <tt>'''Jmol'''</tt> (right at the beginning) must be written as such, since it is the internal name and identification of the unique JSmol object constructor.
  
The following functions all relate to applet creation or display. All of them must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed) --see syntax and examples below.
+
For a start, you may just copy and then adapt this simple example:
 +
<pre>
 +
var Info = {
 +
  color: "#FFFFFF",
 +
  height: 300,
 +
  width: 300,
 +
  script: "load $caffeine",
 +
  use: "HTML5",
 +
  j2sPath: "j2s",
 +
  serverURL: "php/jsmol.php",
 +
};
  
=== getApplet ===
+
Jmol.getApplet("myJmol", Info);
Syntax: <code>Jmol.getApplet = function(id, Info, checkOnly)</code>
+
</pre>
  
This function creates the JavaScript Object that keeps track of the Jmol applet (or the JSmol surrogate if a non-Java option is active). It should be assigned to a variable '''with the same name as the id'''. For example:
+
What this will do is:
myJmol = Jmol.getApplet("myJmol", Info);
+
* Create a JavaScript variable (of the object type) named <code>myJmol</code>.
 +
* Insert a JSmol instance at that point in the web page, 300&times;300 pixels in size, with white background.
 +
* Retrieve data for caffeine from the Cactus server and display the molecular structure in the JSmol panel.
  
<tt>checkOnly</tt> 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 applet ''would'' be created on this particular platform -- a signed Java applet, an unsigned Java applet, a JSmol canvas, an image, a GLmol canvas, etc.
+
If you want more control, keep reading.
  
=== getAppletHtml ===
+
<span style="font-size:1.2em;">
 
+
A '''[[Jmol_JavaScript_Object/Info|detailed explanation]] of the parameters''' included in the <code>Info</code> variable
Syntax: <code>Jmol.getAppletHtml = function(id)</code>
+
</span>
 
+
is available in a separate page, while the major ones and their default values are given below:
Useful for inserting the applet code into the page, in the case when it was generated and stored in a variable (<code>id</code>) after <code>Jmol.setDocument(false)</code>. For example:
 
 
<pre>
 
<pre>
Jmol.setDocument(false);
+
var Info = {
myJmol = Jmol.getApplet("myJmol", Info);
+
  color: "#FFFFFF", // white background (note this changes legacy default which was black)
(...)
+
  height: 300,      // pixels (but it may be in percent, like "100%")
document.getElementById('someContainer').innerHTML = Jmol.getAppletHtml(myJmol);
+
  width: 300,
 +
  use: "HTML5",    // "HTML5" or "Java" (case-insensitive)
 +
  j2sPath: "j2s",          // only used in the HTML5 modality
 +
  jarPath: "java",              // only used in the Java modality
 +
  jarFile: "JmolApplet0.jar",    // only used in the Java modality
 +
  isSigned: false,              // only used in the Java modality
 +
  serverURL: "php/jsmol.php",  // this is not applied by default; you should set this value explicitly
 +
  src: null,          // file to load
 +
  script: null,      // script to run
 +
  defaultModel: "",  // name or id of a model to be retrieved from a database
 +
  addSelectionOptions: false,  // to interface with databases
 +
  disableInitialConsole: false, // shows a bunch of messages while the object is being built
 +
  debug: false
 +
};
 
</pre>
 
</pre>
  
=== getVersion ===
+
==== Setting parameters from the URL ====
 
+
''Jmol 14.0 or later''
Syntax: <code>Jmol.getVersion = function()</code>
 
 
 
This function returns the version of Jmol-JSO, like <code>Jmol-JSO 13.0</code>.
 
 
 
=== resizeApplet ===
 
 
 
Syntax: <code>Jmol.resizeApplet = function(applet,size)</code>
 
 
 
Used to change the dimensions of the specified applet.
 
 
<tt>size</tt>: a value or an array with a pair of width/height values in an array, either expressed in pixels, <code>[300,500]</code> or as percent, <code>["50%", "60%"]</code>.
 
 
 
=== setAppletSync ===
 
 
 
Syntax: <code>Jmol.setAppletSync = function(applets, commands, isJmolJSV)</code>
 
 
 
=== setDocument ===
 
 
 
Syntax: <code>Jmol.setDocument = function(doc)</code>
 
 
 
...(description and details to be filled in here)
 
 
 
If using <code>Jmol.setDocument(false)</code>, the applet may be later inserted using <code>Jmol.getAppletHtml()</code> (see above).
 
 
 
=== setGrabberOptions ===
 
 
 
Syntax: <code>Jmol.setGrabberOptions = function(options)</code>
 
 
 
/*
 
Jmol._grabberOptions = [
 
  ["$", "NCI(small molecules)"],
 
  [":", "PubChem(small molecules)"],
 
  ["=", "RCSB(macromolecules)"]
 
];
 
*/
 
 
 
=== showInfo ===
 
 
 
Syntax: <code>Jmol.showInfo = function(applet, tf)</code>
 
 
 
=== setInfo ===
 
 
 
Syntax: <code>Jmol.setInfo = function(applet, info, isShown)</code>
 
 
 
=== setXHTML ===
 
 
 
Syntax: <code>Jmol.setXHTML = function(id)</code>
 
 
 
 
 
== Control-Specific Functions ==
 
 
 
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 '''<code>Jmol</code>''' object (this name is literal, cannot be changed) --see syntax and examples below.
 
 
 
The first parameter for nearly all of these functions, <tt>appletOrId</tt>, 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 <em style="color:peru;">colored italic font</em> is used for parameters that are optional. 
 
 
 
=== jmolButton ===
 
 
 
Inserts in the page a button with a text label.
 
 
 
Syntax: <code>Jmol.jmolButton(appletOrId, script<em style="color:peru;">, label, id, title</em>)</code>
 
 
 
Example:
 
var myJmol = "myJmol";
 
var myInfo = {
 
  color: "#DDDDFF",
 
  script: "load myMolecule.mol;",
 
  height: 300,
 
  width: 300
 
};
 
myJmol = Jmol.getApplet("myJmol", myInfo);
 
Jmol.jmolButton(myJmol,"spacefill on", "display as vdW spheres");
 
 
 
<tt>script</tt> 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: <code>[funcName, param1, param2, param3...]</code>
 
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.
 
    ....
 
}
 
 
 
<tt>label</tt> is the text in the button; if not specified, it defaults to the first 32 characters of the script.
 
 
 
<tt>id</tt> (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 <code><nowiki><span></nowiki></code> element that will have an HTML id of "span_" plus the given <tt>id</tt>, and an HTML title of the given <code>title</code>.
 
:Browsers will hence show <tt>title</tt> as a tooltip when mouse pointer stays over the button.
 
 
 
=== jmolCheckbox ===
 
Syntax: <code>Jmol.jmolCheckbox(appletOrId, scriptWhenChecked, scriptWhenUnchecked, labelHtml<em style="color:peru;">, isChecked, id, title</em>)</code>
 
 
 
=== jmolCommandInput ===
 
Syntax: <code>Jmol.jmolCommandInput(appletOrId<em style="color:peru;">, label, size, id, title</em>)</code>
 
 
 
=== jmolLink ===
 
Syntax: <code>Jmol.jmolLink(appletOrId, script<em style="color:peru;">, text, id, title</em>)</code>
 
 
 
<tt>script</tt> is run when the user clicks on the link.
 
 
 
<tt>text</tt> is written to the page as a link. If it is not specified, it defaults to the first 32 characters of <tt>script</tt>.
 
 
 
<tt>id</tt> 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 <code><nowiki><span></nowiki></code> element that will have an HTML id of "span_" plus the given <tt>id</tt>, and an HTML title of the given <tt>title</tt>.
 
:Browsers will hence show <tt>title</tt> as a tooltip when mouse pointer stays over the link.
 
 
 
=== jmolMenu ===
 
Syntax: <code>Jmol.jmolMenu(appletOrId, arrayOfMenuItems<em style="color:peru;">, size, id, title</em>)</code>
 
 
 
=== jmolRadio ===
 
Syntax: <code>Jmol.jmolRadio(appletOrId, script<em style="color:peru;">, labelHtml, isChecked, separatorHtml, groupName, id, title</em>)</code>
 
 
 
=== jmolRadioGroup ===
 
Syntax: <code>Jmol.jmolRadioGroup(appletOrId, arrayOfRadioButtons<em style="color:peru;">, separatorHtml, groupName, id, title</em>)</code>
 
 
 
=== setCheckboxGroup ===
 
Syntax: <code>Jmol.setCheckboxGroup(chkMaster,chkBox)</code>
 
 
 
 
 
== HTML-Specific Functions ==
 
  
These simple commands just deliver HTML to the page. They are merely convenience functions for use
+
Some values in the <tt>Info</tt> variable defined in the page may be overriden by the user, by adding a parameter in the page URL. This may be useful for testing, both own and some else's pages.
from within the <code>body</code> so as not to have to continually switch in and out of script tags.  
 
  
Again, all these functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed) --see syntax and examples below.
+
The settable options affect
 +
* what modality of J(S)mol to use, either Java or HTML5
 +
* what kind of applet to use, either 'sandboxed' or 'all-permissions' (new terms, more or less equivalent to the formerly called unsigned and signed applets)
 +
* whether to get the JmolApplet files from some other location (url)
 +
* whether to get the JavaScript files that build the Jmol Object from some other location (url)
  
:Much better practice is to do all control creation in the header of the page, from within jQuery's <code>$(document).ready()</code> function, using <code>Jmol.setDocument(0)</code>, appending the HTML to a growing string using the control-specific functions, then setting the code in a predefined <code>div</code> element using the jQuery <code>$('#divId').html()</code> function.
+
The format for parameters in the url is the standard syntax in so called 'search' part of the url, i.e. <code>?parameter1=value1&parameter2=value2&...etc.</code>
  
=== jmolBr ===
+
Examples (you get the meaning, don't you?):
Inserts a soft line break. Its only use is:
 
Jmol.jmolBr()
 
 
 
=== jmolHtml ===
 
Allows to insert in the page any HTML code you may wish.
 
 
 
Syntax: <code>Jmol.jmolHtml = function(html)</code>
 
 
 
Example:
 
<nowiki>Jmol.jmolHtml(' <b style="color:red">H<sub>2</sub>O</b>')</nowiki>
 
 
 
 
 
== CSS-Setting Functions ==
 
 
 
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:
 
 
<pre>
 
<pre>
  Jmol.setButtonCss(null, "style='width:160px'");
+
any.htm?_USE=html5
 +
any.htm?_USE=java
 +
any.htm?_USE=signed
 +
any.htm?_JAR=http://some.url.com/some/jsmol/java
 +
any.htm?_J2S=http://some.url.com/some/jsmol/j2s
 +
any.htm?_USE=java&_JAR=http://some.url.com/some/jsmol/java
 +
any.htm?_USE=html5&_J2S=http://some.url.com/some/jsmol/j2s
 
</pre>
 
</pre>
  
Again, all these functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed) --see syntax and examples below.
+
Note that the names, like <code>_USE</code>, must be uppercase. The values are case-insensitive.
 
 
=== setAppletCss ===
 
Syntax: <code>Jmol.setAppletCss = function(cssClass, text)</code>
 
 
 
=== setButtonCss ===
 
Syntax: <code>Jmol.setButtonCss = function(cssClass, text) </code>
 
 
 
=== setCheckboxCss ===
 
Syntax: <code>Jmol.setCheckboxCss = function(cssClass, text) </code>
 
 
 
=== setLinkCss ===
 
Syntax: <code>Jmol.setLinkCss = function(cssClass, text) </code>
 
 
 
=== setMenuCss ===
 
Syntax: <code>Jmol.setMenuCss = function(cssClass, text)</code>
 
 
 
=== setRadioCss ===
 
Syntax: <code>Jmol.setRadioCss = function(cssClass, text)</code>
 
 
 
 
 
== Public Jmol Applet methods ==
 
 
 
All these functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed) --see syntax and examples below.
 
 
 
(''TO-DO -- just transfer text with slight modification from [{{Website}}jslibrary/ jslibrary]'')
 
 
 
Syntax:
 
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)
 
  
 +
== Functions for Jmol JavaScript Object ==
  
== Methods specific to optional components ==
+
Please see [[Jmol_JavaScript_Object/Functions]] for details about:
* [[Jmol_JavaScript_Object/JME|Methods specific to the JME applet]]
+
* Functions for creation or display of Jmol Objects
* [[Jmol_JavaScript_Object/JSV|Methods specific to the JSpecView applet]]
+
* Functions for creating controls
 +
* Functions that insert HTML
 +
* Functions that set CSS rules
 +
* Functions that interact with a running Jmol Object
 +
* Deprecated, unnecessary or not recommended
 +
* Methods specific to optional components

Latest revision as of 16:00, 18 April 2024


Geographylogo.png

Reference: English – Other: 日本語 ·


JSmol, the Jmol JavaScript Object

JSmol logo13.png

The heart of JSmol is the Jmol JavaScript object, (window.Jmol), which includes a set of JavaScript functions and utilities. The initial Jmol object was developed by Bob Hanson and Paul Pillot in early 2012. It was folded into JSmol later that year. The library File icon.gif JSmol.min.js provides this object and supersedes the Jmol.js JavaScript library formerly used exclusively with the Jmol Java applet, 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 and selectively replaced by a non-Java HTML5 canvas element (which might not even be Jmol).

Using JSmol, a web page developer can target most web browsers that no longer support Java applets, using a Jmol applet surrogate, while still implementing the Jmol Java applet on compatible platforms.

JSmol 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.

In addition, JSmol allows easy interaction with

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

JSmol is fully compatible with jQuery 1.9 or 1.10. (jQuery 2.0 does not and for reasons of principle reportedly will never support MSIE running locally using file://, so if you do not need to run your page in MSIE in a local environment, that should be fine. There is a fix for this, however, if you must do that. In that case you must hack jQuery a bit.) The library has been W3C and XHTML validated.

Main features of JSmol

Non-Java optionsOptions for HTML5-only and optionally Java and HTML5/WebGL. 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 File icon.gifJSmol.min.js as well as Folder icon.gifj2s; for internationalized interface, also Folder icon.gifidioma. Also optionally Folder icon.gifjava.
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() or Jmol.getAppletHtml() 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 applet/canvas itself. The applet or canvas is wrapped in a set of div elements, allowing a richer diversity of options.
AJAX JSmol includes methods to easily access cross-platform resources using AJAX provided by jQuery.
REST services JSmol lets you access keyword search results from RCSB -- for example, a list of all structures that reference caffeine.
Scripting JSmol provides the same full complement of scripting that Jmol offers. JSmol accepts script commands immediately, before or during applet/canvas creation on the page, caching them until Jmol is ready to accept them.

JSmol

JSmol logo13.png

JSmol is the name for the HTML5 canvas version of the former Jmol applet. JSmol opens up the use of Jmol in PC, Mac, and Linux systems, tablets and phones (both iOS and Android) without the need for Java. 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 do require a server-side PHP script, commonly provided as File icon.gifphp/jsmol.php –read details below.)

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:
    • Opera allows no access to local files.
    • MSIE allows access to local files only if they are not binary.
    • Chrome allows access only when Chrome has been started using a special command-line flag (chrome.exe --allow-file-access-from-files).
    • Firefox allows access only after setting a special about:config flag (security.fileuri.strict_origin_policy = false).
  • Opening binary files (e.g Spartan files, gzipped files, File icon.gifpngj files): they can be read but must be identified as such in their file name (see below).
  • Writing of File icon.gifjpg, File icon.gifpng and File icon.gifpngj (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.
  • The WebGL modality of JSmol has not been fully developed and feature 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.

File names

JSmol will determine whether a file is binary or not —before loading it— by inspection of the file name. JSmol will switch to binary mode for files with any of the following in their file name: File icon.gif.bin File icon.gif.gz File icon.gif.zip File icon.gif.jpg File icon.gif.png File icon.gif.jmol File icon.gif.smol File icon.gif.spartan File icon.gif.mrc File icon.gif.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.

Advanced: If you need a different extension to be read as binary, and cannot change the file names to include one of the default extensions, it is possible to extend the set using this code in your JavaScript after the Jmol object has being initialized: Jmol._binaryTypes.push('.myExtension');

Browser behaviour

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.)

If your page visitors need to read binary files, place a copy of the File icon.gifjsmol.php file that is included in the JSmol distribution (see below) on your server and point to it using the serverURL item of the Info array. As an example, the demo pages use this approach.

For that to work, your server must support PHP. Otherwise, you might "borrow" by pointing to the File icon.gifjsmol.php file in another server that can run PHP (please, ask the owner of that server).

In Chrome and also other browsers, you may overcome problems with loading local binary files by running pages through a local web server.

Converting legacy web pages to JSmol

It is not hard to convert pages that used the Jmol Applet and the Jmol.js library to use the HTML5 versions of JSmol. See more details.

Installation

See Jmol JavaScript Object/Installation

Initialization

Browser issues

JSmol makes strong use of the HTML5 features. Therefore, it is only compatible with modern web browsers. Specifically, Internet Explorer must be version 9 or higher.

In addition, it is important to use a doctype in the header of the html page. The recommended doctype is the simple one, associated to HTML5 standard, as the very first line of your html document.

Also, for full compatibility, particularly for the localization (language translations) of the JSmol pop-up menu, you should declare the charset as UTF-8 and save the html document (and all accessory files) using UTF-8 encoding (usually without BOM, but this needs further confirmation; recent versions of Firefox seem to have problems with non-BOM UTF-8 files, and UTF-8 with BOM looks like a better solution).

Therefore your html documents should start as:

<!DOCTYPE HTML>
<html>
<head>
<meta charset="utf-8">

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 JSmol depends upon whether the page is loaded using "file:" or "http:"
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 File icon.gif.html page.
All this needs confirmation. See also Java security policy which applies to the Java applet.

Lightweight JSmol

There is an alternative version of Jmol object that, using the HTML5 canvas like JSmol, loads very fast while offering minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at smartphones and such systems with limited resources.

For more details on how to use this, see Lightweight JSmol.

Optional components

Setting parameters

The essential and minimal call to create a JSmol object is simply:

Jmol.getApplet("myJmol")

This will create a myJmol global variable in JavaScript that holds the JSmol object and is also the unique ID for that object in all functions and methods described below. Note that this simplest syntax will only work when the html file is located in the root JSmol folder.

However, in most situations you will want to customize some aspects, like the size of the object and the file paths. All of the initialization parameters can be specified.

The regular call to create a JSmol object with specified characteristics is to define an Info variable, which is an associative array (a set of key+value pairs) that indicates all the desired characteristics of the JSmol object. The JSmol.min.js library will provide a default Info variable, so you only need to specify those keys which values you want to customize.

Once Info has been defined, you create and insert the JSmol object in the page using this:

Jmol.getApplet("myJmol", Info)

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 JSmol object that is being created. You may wish to have two JSmols 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. In contrast, Jmol (right at the beginning) must be written as such, since it is the internal name and identification of the unique JSmol object constructor.

For a start, you may just copy and then adapt this simple example:

var Info = {
  color: "#FFFFFF",
  height: 300,
  width: 300,
  script: "load $caffeine",
  use: "HTML5",
  j2sPath: "j2s",
  serverURL: "php/jsmol.php",
};

Jmol.getApplet("myJmol", Info);

What this will do is:

  • Create a JavaScript variable (of the object type) named myJmol.
  • Insert a JSmol instance at that point in the web page, 300×300 pixels in size, with white background.
  • Retrieve data for caffeine from the Cactus server and display the molecular structure in the JSmol panel.

If you want more control, keep reading.

A detailed explanation of the parameters included in the Info variable is available in a separate page, while the major ones and their default values are given below:

var Info = {
  color: "#FFFFFF", // white background (note this changes legacy default which was black)
  height: 300,      // pixels (but it may be in percent, like "100%")
  width: 300,
  use: "HTML5",     // "HTML5" or "Java" (case-insensitive)
  j2sPath: "j2s",          // only used in the HTML5 modality
  jarPath: "java",               // only used in the Java modality
  jarFile: "JmolApplet0.jar",    // only used in the Java modality
  isSigned: false,               // only used in the Java modality
  serverURL: "php/jsmol.php",  // this is not applied by default; you should set this value explicitly
  src: null,          // file to load
  script: null,       // script to run
  defaultModel: "",   // name or id of a model to be retrieved from a database
  addSelectionOptions: false,  // to interface with databases
  disableInitialConsole: false, // shows a bunch of messages while the object is being built
  debug: false
};	 

Setting parameters from the URL

Jmol 14.0 or later

Some values in the Info variable defined in the page may be overriden by the user, by adding a parameter in the page URL. This may be useful for testing, both own and some else's pages.

The settable options affect

  • what modality of J(S)mol to use, either Java or HTML5
  • what kind of applet to use, either 'sandboxed' or 'all-permissions' (new terms, more or less equivalent to the formerly called unsigned and signed applets)
  • whether to get the JmolApplet files from some other location (url)
  • whether to get the JavaScript files that build the Jmol Object from some other location (url)

The format for parameters in the url is the standard syntax in so called 'search' part of the url, i.e. ?parameter1=value1&parameter2=value2&...etc.

Examples (you get the meaning, don't you?):

any.htm?_USE=html5
any.htm?_USE=java
any.htm?_USE=signed
any.htm?_JAR=http://some.url.com/some/jsmol/java
any.htm?_J2S=http://some.url.com/some/jsmol/j2s
any.htm?_USE=java&_JAR=http://some.url.com/some/jsmol/java
any.htm?_USE=html5&_J2S=http://some.url.com/some/jsmol/j2s

Note that the names, like _USE, must be uppercase. The values are case-insensitive.

Functions for Jmol JavaScript Object

Please see Jmol_JavaScript_Object/Functions for details about:

  • Functions for creation or display of Jmol Objects
  • Functions for creating controls
  • Functions that insert HTML
  • Functions that set CSS rules
  • Functions that interact with a running Jmol Object
  • Deprecated, unnecessary or not recommended
  • Methods specific to optional components