Jmol JavaScript Object/Info

Documentation of parameters of the Info variable

This page explains the parameters of the Info variable, an essential part of the Jmol JavaScript Object.

Info is an associative array (a set of key/value pairs) indicating all the desired characteristics of the Jmol object (Jmol applet or JSmol). For a full, up-to-date description of all of the options, see JmolApi.js. It is recommended that any page developer interested in utilizing Jmol extensively takes a look at this file.

Values may be defined

• either during initialization of the Info variable:

  var Info = {
    color: "#E8F4FF",
    height: 400,
    width: 400
  };

• or separately:

  Info.color = "#E8F4FF";

Jmol object definition

(The values shown in the listing below are the defaults)

Dimensions

• height 300

The size of the Jmol object in pixels or expressed as percent of its container height as a string in quotes: "100%".

• width 300

The width of the Jmol object 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 attributes style=height:... and style=width:.... That includes setting height to 100% for body and html. Note also that, despite that, non-Java JSmol uses the canvas element, which will not resize correctly.

Background color

• color "white"

The background color of the Jmol object, as a quoted text string in any JmolScript-supported format: color name, decimal triplet [r,g,b] or hexadecimal [xRRGGBB]. Note that default is now white, in contrast to black in the classic Jmol.js method.

Files and paths

• jarFile "JmolApplet0.jar"

(Java modality only) The file to be 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. Be careful that the setting here should match that of isSigned.

• isSigned false

(Java modality only) Make sure to change this to true if the file indicated for jarFile is the signed applet.

• jarPath "."

(Java modality only) 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.

• j2sPath "j2s"

(HTML5 modality) The path to j2s including its own name; the contents of this folder are essential for JSmol to work.

Modality

• use "Java noWebGL noHTML5 noImage" This string determines the various options to be tried (applet and surrogates) and the order in which to try them.
  • The default setting is the same as just Java by itself and indicates to just use Java (and display a message if Java is not enabled).
  • The value HTML5 forces use of JSmol in html5-only mode.
  • 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 JSmol or maybe GLmol or HTML5-only ChemDoodle (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 some browsers. Thus, users intentionally disabling Java may only get the Java modality, and a message will be displayed that Java is not available.

Startup period

(The values shown in the listing below are the defaults)

• coverImage ""

Set the path and filename of an image that will be displayed on top of the Jmol object (usually as an initial replacemente or during loading, see deferApplet and deferUncover parameters below).

• coverTitle ""

Set a tip that is displayed before model starts to load.

• coverCommand ""

Set a Jmol command or script that will be executed upon clicking the cover image.

• deferApplet false

If set true, the model will not be loaded until the user clicks on the cover image (see coverImage parameter above).

• deferUncover false

If set true, the cover image will remain until command execution is complete.

• disableInitialConsole false

If set true, avoids the display of messages ('console') in the Jmol panel while the Jmol object is being built initially.

• disableJ2SLoadMonitor false

If set true, avoids the display of messages in a single line, colored, at bottom-left of the page while code loads (both initially and every time a new module is requested by a running script).

• readyFunction ""

The name of a JavaScript function to call when the Jmol object has been created and is ready to receive commands (and also called when the object is destroyed e.g. when the page is closed).

For example, with 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!'); }

Model loading

(The values shown in the listing below are the defaults)

• defaultModel ""

A model to be retrieved from a public database and displayed when the Jmol object has finished loading.

• script ""

A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed.

• src ""

is the same as script (only included because it is the syntax commonly used for images).

Customization or extras

(The values shown in the listing below are the defaults)

• addSelectionOptions false

Set this value to true if you want to display, below the Jmol object, a menu with options for loading structures from public databases.

• console "***_infodiv"

The ID in html of the container or div that will receive output from Jmol. Default value is the Jmol Object name/id followed by "_infodiv", and it is contained in the info panel that may be displayed alternatively to the Jmol viewer.

• debug false

Set this value to true if you are having problems getting your page to show the Jmol object, buttons or ther controls.

• memoryLimit 512

(Java modality only) The maximum amount of memory allowed for the Java applet, in MB.

• serverURL "http://chemapps.stolaf.edu/jmol/jsmol/jsmol.php"

The URL of the server to be used for getting file data into non-Java modalities. This can be left as default, 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.

• usecommandthread false

The signed Jmol Java 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.

Callbacks

There are several parameters that in Jmol.js could be set using the jmolSetParameter() or jmolSetCallback() functions. These are discussed in sets:

• animframecallback
• appletreadycallback
• atommovedcallback
• echocallback
• evalcallback
• hovercallback
• loadstructcallback
• messagecallback
• pickcallback
• measurecallback
• minimizationcallback
• resizecallback
• scriptcallback
• synccallback

These callbacks allow the page designer to get information about what is happening within the Jmol object. The name of a JavaScript function, in single- or double-quotes should be given here if desired. Do not use function() {....} syntax.

Misc.

• language

This setting can be used to specify a language to be used in the JmolApplet interface (only for the Java version and primarily for testing; the default language used in the applet is automatically detected from the system settings of the user's browser).

Please note that language (localization) is not currently implemented in non-Java surrogates (including JSmol).

• boxbgcolor
• boxfgcolor
• boxmessage
• progressbar
• progresscolor

These five values generally should not be adjusted.

Contributors

AngelHerraez