Difference between revisions of "Jmol JavaScript Object"

From Jmol
Jump to navigation Jump to search
m (Initialization parameters)
(more details on Info parameters)
Line 154: Line 154:
 
: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.
 
: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.
  
<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:
+
<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:
  
 
<pre>
 
<pre>
Line 176: Line 176:
 
</pre>
 
</pre>
  
* '''Info.addSelectionOptions''' Set this value to <code>true</code> if you want the user to see a menu with public database options.
+
* '''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.
* '''Info.color'''  The background color of the applet.
+
* '''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).
 
* '''Info.debug'''  Set this value to <code>true</code> if you are having problems getting your page to show the applet or buttons.
 
* '''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 from a public database to obtain and display when the applet is loaded.
+
* '''Info.defaultModel''' A model to be retrieved from a public database and displayed when the applet is loaded.
* '''Info.height'''  The width of the applet 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 must explicitly implement the CSS attribute <code>style=height:...</code>.
+
* '''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 <code>jarFile</code> is the signed applet.
+
* '''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 JmolApplet0.jar (for faster incremental loading) or JmolApplet.jar (a single 2.5+MB download).
+
* '''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 jar file. Note that if the unsigned applet is used and the page is tested locally, then all model files must in or under the directory indicated by this value.
+
* '''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''' Then maximum amount of memory allowed the applet, in MB.
+
* '''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 when the page is closed).
+
* '''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:
 
*: 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(theJmol) { document.title = theJmol._id + " is ready"; }</code>
Line 191: Line 191:
 
*: <code>function jmolIsReady() { 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.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 non-Jmol options to get file data. This can be left as "http://chemapps.stolaf.edu/jmol/jmolcd.php", as 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.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.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 and the order in which to try them. The default setting of "Java noWebGL noHTML5 noImage" is the same as just "Java" by itself and indicates to just use Java (and display a message if Java is not enabled). A value of "Java Image" 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 "Java HTML5" would test for Java and then, if that is not available, use GLmol or HTML5-only ChemDoodle (whichever is made available). The value "Java WebGL HTML5 Image" allows all standard platforms at least some model. 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.use''' This string determines the various options to be tried (applet and surrogates) and the order in which to try them.
* '''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>.
+
** 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 jmolSetParameter() or jmolSetCallback() functions. These are discussed in sets:
+
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:
  
 
* '''Info.animframecallback'''
 
* '''Info.animframecallback'''
Line 213: Line 218:
 
* '''Info.synccallback'''
 
* '''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 function() {....} syntax.
+
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.
  
 
* '''Info.language'''  
 
* '''Info.language'''  
 
 
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).
 
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).
  
* '''usecommandthread'''
+
* '''Info.usecommandthread'''
 
 
 
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.
 
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.
  
Line 228: Line 231:
 
* '''Info.progressbar'''
 
* '''Info.progressbar'''
 
* '''Info.progresscolor'''
 
* '''Info.progresscolor'''
 
 
These five values generally should not be adjusted.
 
These five values generally should not be adjusted.
  

Revision as of 20:41, 11 November 2012

This page is under construction.


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 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 third-party non-Java visualization resource (using WebGL and/or HTML5) or an image, depending on client's platform resources.

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 GLmol, ChemDoodle, JSmol or just an image) while still implementing Jmol itself on traditional platforms. Compromises will have to be made, because no other resource has 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...."

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

Representative differences between Jmol-JSO and Jmol.js

AspectJmol-JSOJmol.js
Non-Java OptionsAutomatically switches to non-Java surrogates.No such capability.
Library Files Requires at a minimum, File icon.gifJmolCore.js, File icon.gifJmolApplet.js, and File icon.gifJmolApi.js. Requires only File icon.gifJmol.js
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. Creates the _jmol associative array, but only uses it to hold parameter and variable values.
JavaScript Prototypes The object you create using Jmol.getApplet() is a JavaScript object that is a subclass of Jmol._Applet (generally). When you use Jmol.getApplet(), 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. jmolApplet() creates the applet with a given id and name (such as "jmolApplet0"), but no JavaScript wrapper object for it.
AJAX Jmol-JSO includes methods to easily access cross-platform resources using AJAX provided by jQuery. No AJAX support.
Scripting Starts accepting script commands immediately, caching them until the Java applet is ready to accept them. Cannot accept script commands until the Java applet is fully initialized. (Requires some sort of applet-ready callback.)

Installation

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

  • File icon.gifJmolApplet.jar or File icon.gifJmolAppletSigned.jar or File icon.gifJmolApplet0*.jar or File icon.gifJmolAppletSigned0*.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 security policy imposes limitations on the folder location of files.

The basic suite of JavaScript libraries include these four:

  • File icon.gifJmolCore.js (required)
  • File icon.gifJmolApplet.js (required)
  • File icon.gifJmolControls.js (optional -- required if any buttons or links or other input methods will be used)
  • File icon.gifJmolApi.js (required)

However, AJAX access (by the unsigned applet or non-Java resources) to cross-domain resources such as public databases also requires File icon.gifjQuery.min.js and File icon.gifjQuery.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 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 bug report if you find a problem. These libraries include:

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>

JME integration

The JME applet allows the user to draw a molecular structure in 2D. Jmol-JSO includes the capability to pass information back and forth between Jmol and JME in a seamless manner. The "information panel" that Jmol-JSO implements can be set up to hold the JME applet, allowing tight integration. Alternatively, the JME applet and the Jmol applet can be set side-by-side on a web page, and applet-applet communication can be handled by the page developer. Create a JME applet using Jmol.getJMEApplet().

JSpecView integration

Extensive work in 2012 integrated JSpecView into Jmol 13. The full Jmol application includes a new "tools" menu item that opens a frame for JSpecView. For the applet, Jmol and JSpecView are two distinct applets that talk between themselves using the Jmol SYNC command. Jmol-JSO brokers this transaction and allows coordinated applet start-up so that one applet does not send a command to the other before both are ready.

Associated with this integration, we have designed a specification for an extension of the JCAMP-DX format that allows one JDX file to contain Jmol-readable models and peak information, allowing the user to click on, for example, a carbon atom in Jmol and have the C-13 NMR spectrum automatically display and highlight the associated peak in JSpecView. For a demonstration of the Jmol/JSpecView connection, see the JSpecView subdirectory at chemapps.stolaf.edu or the demo pages at the University of the West Indies.

Initialization parameters

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:

myJmol = 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 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.
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.

Info 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 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:

var Info = {
  addSelectionOptions: false,
  color: "#FFFFFF",
  debug: false,
  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
};	 
  • Info.addSelectionOptions Set this value to true if you want to display, below the applet, a menu with options for loading structures from public databases.
  • Info.color The background color of the applet, in any JmolScript-supported format: color name, decimal triplet [r,g,b] or hexadecimal [xRRGGBB]. Note that default is white (it is black in the classic Jmol.js method).
  • Info.debug Set this value to true 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 body and html) must explicitly implement the CSS attribute style=height:....
  • Info.isSigned Make sure to change this to true if the file indicated for Info.jarFile is the signed applet.
  • Info.jarFile The file used, usually either JmolApplet0.jar (for faster incremental loading) or JmolApplet.jar (a single 2.5+ MB download), or the signed versions JmolAppletSigned0.jar and JmolAppletSigned.jar.
  • 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 Info.readyFunction: jmolIsReady any of the following JavaScript function definitions could be used:
    jmolIsReady = function(theJmol) { document.title = theJmol._id + " is ready"; }
    jmolIsReady = function() { alert('Welcome to Jmol!'); }
    function jmolIsReady() { alert('Welcome to Jmol!'); }
  • 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 Java noWebGL noHTML5 noImage is the same as just Java by itself and indicates to just use Java (and display a message if Java is not enabled).
    • A value of Java Image 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 Java HTML5 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 Java WebGL HTML5 Image 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 style=width:....

In addition to these keys are a set of parameters that using Jmol.js could be set using the jmolSetParameter() or jmolSetCallback() functions. These are discussed in sets:

  • Info.animframecallback
  • 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 function() {....} syntax.

  • Info.language

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

  • Info.usecommandthread

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
  • Info.boxfgcolor
  • Info.boxmessage
  • Info.progressbar
  • Info.progresscolor

These five values generally should not be adjusted.

Applet Creation or Display Functions

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.

getApplet

getJMEApplet

getJSVApplet

Syntax: Jmol.getApplet = function(id, Info, checkOnly)
Jmol.getJMEApplet = function(id, Info, linkedApplet)
Jmol.getJSVApplet = function(id, Info)

These above three functions create the JavaScript Objects that keep track of the Jmol, JME, or JSpecView applet, respectively (or the Jmol surrogate if a non-Java option is active). In each case, they should be assigned to a variable with the same name as the id. For example:

myJmol = Jmol.getApplet("myJmol", Info);
myJME = Jmol.getJMEApplet("myJME", Info, myJmol);
mySpec = Jmol.getJSVApplet("mySpec", Info);

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 applet would be created on this particular platform -- a signed Java applet, an unsigned Java applet, an image, a GLmol canvas, a 2D ChemDraw canvas, or a 3D ChemDraw canvas.

linkedApplet can be set to a Jmol JavaScript Object that will contain this JME drawing panel as a 2D input option in its info panel.

getAppletHtml

Syntax: 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(false). For example:

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

getVersion

Syntax: Jmol.getVersion = function()

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

resizeApplet

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

Used to change the dimensions of the specified applet.

size: a value or an array with a pair of width/height values in an array, either expressed in pixels, [300,500] or as percent, ["50%", "60%"].

setAppletSync

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

setDocument

Syntax: Jmol.setDocument = function(doc)

...(description and details to be filled in here)

If using Jmol.setDocument(false), the applet may be later inserted using Jmol.getAppletHtml() (see above).

setGrabberOptions

Syntax: Jmol.setGrabberOptions = function(options)

/*
Jmol._grabberOptions = [
  ["$", "NCI(small molecules)"],
  [":", "PubChem(small molecules)"],
  ["=", "RCSB(macromolecules)"]
];
*/

showInfo

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

setInfo

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

setXHTML

Syntax: Jmol.setXHTML = function(id)


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:

  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.

setAppletCss

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

setButtonCss

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

setCheckboxCss

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

setLinkCss

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

setMenuCss

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

setRadioCss

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


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

jmolButton

Inserts in the page a button with a text label.

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

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");

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.

jmolCheckbox

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

jmolCommandInput

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

jmolLink

Syntax: 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.

jmolMenu

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

jmolRadio

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

jmolRadioGroup

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

setCheckboxGroup

Syntax: Jmol.setCheckboxGroup(chkMaster,chkBox)


HTML-Specific Functions

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.

jmolBr

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: Jmol.jmolHtml = function(html)

Example:

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


Public Jmol Applet 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)

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) 


JME-Specific Functions

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

Syntax:

Jmol.jmeGetFile = function(jme, asJME) 
Jmol.jmeOptions = function(jme, options)
Jmol.jmeReadMolecule = function(jme, jmeOrMolData)
Jmol.jmeReset = function(jme) 
Jmol.jmeSmiles = function(jme, withStereoChemistry)


JSpecView-Specific Functions

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

Syntax:

Jmol.jsvAddHightlight = function(jsvApplet, x1, x2, r, g, b, a) 
Jmol.jsvExport = function(jsvApplet, exportType, n) 
Jmol.jsvGetCoordinate = function(jsvApplet) 
Jmol.jsvGetPropertyAsJavaObject = function(jsvApplet, key) 
Jmol.jsvGetPropertyAsJSON = function(jsvApplet, key) 
Jmol.jsvGetSolnColour = function(jsvApplet) 
Jmol.jsvIsPro = function(jsvApplet) 
Jmol.jsvIsSigned = function(jsvApplet) 
Jmol.jsvLoadInline = function(jsvApplet, data, params)
Jmol.jsvRemoveAllHighlights = function(jsvApplet) 
Jmol.jsvRemoveHighlight = function(jsvApplet, x1, x2)
Jmol.jsvReversePlot = function(jsvApplet) 
Jmol.jsvRunScript = function(jsvApplet, script)
Jmol.jsvRunScriptNow = function(jsvApplet, script) 
Jmol.jsvSetFilePath = function(jsvApplet, tmpFilePath) 
Jmol.jsvSetSpectrumNumber = function(jsvApplet, n) 
Jmol.jsvSetVisible = function(jsvApplet, TF)
Jmol.jsvSyncScript = function(jsvApplet, peakScript)
Jmol.jsvToggleCoordinate = function(jsvApplet)
Jmol.jsvToggleGrid = function(jsvApplet) 
Jmol.jsvToggleIntegration = function(jsvApplet)
Jmol.jsvWriteStatus = function(jsvApplet, msg)