Revision as of 20:18, 26 November 2019

Jmol.js JavaScript Library

Please, note that the use of this library is deprecated and no longer recommended. Documentation is kept here only for historical reasons, and as a possible reference for those still using the Jmol2.js adapter library.

This documentation used to be available at Jmol website, http://jmol.org/jslibrary/

Basic Scripting Commands

(Parameters with dotted underline are optional)

jmolInitialize

jmolInitialize(JmolFolder)

Initializes the Jmol.js JavaScript library. The call to jmolInitialize() may be within the <head> or the <body> of the HTML page, but must be located before any other calls belonging to Jmol.js. The first parameter, JmolFolder, is compulsory and specifies (between quotes) the relative path of the directory (folder) containing JmolApplet0.jar and the other applet files.

Advanced:

jmolInitialize() may be omitted if you want to use JmolApplet.jar and that file is in the same directory as the HTML page.

Using signed applet or custom applets

Advanced:

jmolInitialize(JmolFolder, useCustomApplet)
jmolInitialize(JmolFolder, useSignedApplet)

If the second parameter is a string (e.g. "myJarFile.jar"), it will be interpreted as the filename of your own, custom, jar file to be used. (And if it's "JmolApplet0.jar", then all the other jar files will also be used.)

If it's not a filename, it will be interpreted as a logical (true/false) value for using or not the signed applet (which has less Java security restrictions than the unsigned applet). If this parameter is omitted (as in the very first syntax given above), it defaults to "false", i.e. use the unsigned applet.

With the signed applet, you can put applet files, model files and page files wherever you want to and run them from local disk. It also allows to load local files into Jmol. The users will receive a security warning from Java asking whether they accept the use of the signed applet (please, beware that this may deter novice users from entering the pages, unless you first give them precise advice that this will show up and is not harmful).

jmolApplet

jmolApplet(size, script, nameSuffix)

Defines and inserts a JmolApplet into the page.

size can be:

For a square applet, a single value;
For a rectangular applet, an array containing two elements, width and height; this is usually easiest to do using JavaScript square bracket notation for array constants, as in [400, 200], ["50%", "100%"] or [0.5, 1.0].
Each dimension (size, width, height) may be specified as:
- an integer pixel count (between 25 and
- a percent value, ending in % and surrounded by quotes (but see notes below); this will be interpreted by the browser as percentage of the dimensions of the surrounding layer (window, frame or DIV); depending on which is the surrounding layer and its properties, this allows to have an applet that is dynamically resized when the browser window is resized;
- a number between zero and 1; this will be multiplied by 100 and interpreted as

Note 1: Percent values for size, and numbers below 1, are only available in Jmol.js accompanying Jmol version 11.0.2 or later in the 11.0 series, and version 11.1.28 or later.

Note 2: Be cautious using percent values for size, as it may give undesired results in old browsers.

Note 3: For cross-browser compatibility, percent height requires that the layer surrounding the applet has an explicit height value (otherwise, the applet will have zero height in some browsers). This can be a pixel count or, if you want height to be relative to window height, you must specify a CSS height attribute of 100% for both html and body.

script (optional) is a script that will be run; this usually loads a model and then modifies its rendering.

nameSuffix (optional) needs only be specified if you want to explicitly control the name and id attributes used as part of the applet tag. The suffix which you supply will be appended to the string "jmolApplet", so if you specify "Foo" the attributes generated will be name='jmolAppletFoo' id='jmolAppletFoo'. In a database application where you are writing records to a table you can feel free to provide an integer as your suffix. If nameSuffix is not provided, applets will take by default the names jmolApplet0, jmolApplet1, etc., in the order they are inserted into the page.

When several applets are inserted in one page, the nameSuffix, explicit or implicit, is important so that later commands that set an action, like jmolSetTarget, jmolScript, or jmolLoadInlineScript, are applied to the intended applet.

Advanced (for testing or debugging):

If you place "?NOAPPLET" (uppercase) at the end of the URL in the browser, the applet will not be inserted into the web page, but instead an informative textarea will be shown.

This can be used for testing the action of buttons and other controls. They still work, but instead of effecting script commands, they display in the textarea the command that would have been sent to the applet if the applet had been there.

Note:

It takes some time to build the applet, so if you put some immediate action like jmolScript() or jmolLoadInline() right after the jmolApplet() line, it will probably fail because it will be called before the applet has finished loading. There are three alternatives that will work:

Put the commands inside the call to jmolApplet() (its 2nd argument, script).
Have the browser wait until the applet has finished. To do so, put this at the end of the script sent with applet creation: javascript appletHasLoaded(); and define a JavaScript function called appletHasLoaded() (or any other name you like) that will trigger any further commands.
Better yet, use appletReadyCallback called before jmolApplet():

jmolSetCallback("appletReadyCallback","appletHasLoaded");

and then define your appletHasLoaded() function to trigger further action.

jmolButton

jmolButton(script, label, id, title)

Draws a button with a text label.

script is run when the button is pressed. If the page contains several Jmol applets, commands will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

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

jmolLink

jmolLink(script, text, id, title)

script is run when the user clicks on the link. If the page contains several Jmol applets, commands will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

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

jmolCheckbox

jmolCheckbox(scriptWhenChecked, scriptWhenUnchecked, labelHtml, isChecked, id, title)

Displays a checkbox, followed immediately by labelHtml.

scriptWhenChecked is run when the checkbox is checked by the user.

scriptWhenUnchecked is run when the user unchecks the checkbox.

If the page contains several Jmol applets, commands in the scripts will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

Optional isChecked should be set to a non-false value (e.g.: true) if you want the checkbox to be checked or marked upon page loading (default: unchecked).

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

Advanced:

In addition, the checkbox and its label will be included in a element that will have an HTML id of "span_" plus the given id, and an HTML title of the given title (optional).

Browsers will hence show title as a tooltip when mouse pointer stays over the checkbox or over its accompanying labelHtml.

The label will be surrounded by <label> tags; the effect is that clicking on the label text will have the same effect as clicking on the checkbox itself.

jmolRadioGroup

jmolRadioGroup(arrayOfRadioButtons, separatorHtml, groupName, id, title)

Used to put up a group of mutually-exclusive radio buttons. arrayOfRadioButtons is usually specified using the JavaScript square brackets [ entryA, entryB, ... ] notation. Each entry is generally another array which contains a script, a label, and an optional isChecked flag. If an entry is a single string instead of an array, then that string is used for both the script and the label.

If the page contains several Jmol applets, commands in the scripts will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

separatorHtml is used to specify HTML code that should be placed after each radio button. For example, to put the radio buttons on separate lines you should pass in "<br>" as the actual parameter. If separatorHtml is not specified, it defaults to " " (i.e., a non-breaking space).

groupName will be used as the common HTML name for all radio buttons in the group. It will default to jmolRadioGroup0, jmolRadioGroup1, etc.

Advanced:

The whole group of radio buttons will be included in a element that will have as its HTML id the value of id or, if this is not given, the value of groupName (optional).

In turn, each radio button + label will have as its HTML id "span_" plus the group's id plus an underscore plus a sequential number (starting at zero), and as its HTML title, the common title (optional).

Each radio button label will be surrounded by <label> tags; the effect is that clicking on the label text will have the same effect as clicking on the radio button itself.

jmolMenu

jmolMenu(arrayOfMenuItems, menuHeight, id, title)

Used to display a menu of items along with associated scripts. arrayOfMenuItems is usually specified using the JavaScript square brackets [ itemA, itemB, ... ] notation. Each item is generally another array which contains a script, a label, and an optional isChecked flag. If an item is a single string instead of an array, then that string is used for both the script and the label.

If the page contains several Jmol applets, commands in the scripts will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

menuHeight is used to specify the height of the menu. If unspecified or 1, the menu is a combo-box that drops down when the user clicks on it. If it is 2 or greater then a menu with the specified number of lines will be displayed. If the value is -1, then the menu will be high enough to show all items, thereby eliminating any scrolling.

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

Advanced: In addition, the menu will be included in a element that will have an HTML id of "span_" plus the given id, and an HTML title of the given title (optional).

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

Advanced: Option groups can be set (in HTML syntax, optgroup) in this way:

Add the optgroup entry as one more element in the arrayOfMenuItems. For that entry, the first element in the sub-array must be "#optgroup" (instead of a script); the second element, the caption wanted for the group ("label" in HTML syntax; cannot contain single quotation mark or apostrophe); the third element will not be used. Then add an extra entry to mark the end of the group, whose first element must be "#optgroupEnd" (second and third elements are ignored).

Example:

jmolMenu([
  [null, ".... select ....", true],
  ["color cpk", "CPK pattern"],
  ["#optgroup", "... Color by: ...."],
  ["color structure", "structure"],
  ["color chain", "chain"],
  ["color group", "group"],
  ["#optgroupEnd"],
  ["#optgroup", ".... Other colors: ...."],
  ["color formalcharge", "electric charge"],
  ["color amino", "amino pattern"],
  ["color shapely", "shapely pattern"],
  ["#optgroupEnd"]
]);

Intermediate Scripting Commands

jmolSetAppletColor

jmolSetAppletColor(boxbgcolor, boxfgcolor, progresscolor)

Used to set the background color of the applet. Colors are specified using HTML "#RRGGBB" notation (Red, Green, Blue, hexadecimal values) or as one of the JavaScript color names.

This command must be issued before jmolApplet.

Advanced:

The text color and progress bar color for the Java Plug-in can optionally be set. (These are not used by modern versions of Java.)

jmolResizeApplet

jmolResizeApplet(size, targetSuffix)

Used to change the dimensions of an existing applet.

size: a value or an array with a pair of values; see details of accepted formats under the jmolApplet function.

Special case: if either width or height value is empty (e.g. ""), that dimension will not be resized.

When more than one JmolApplet is being displayed, targetSuffix is used to specify which one will be resized; default is "0" (i.e., the first applet in the page).

Note:

Implemented only in Jmol.js accompanying Jmol version 11.7.42 or later.

jmolHtml

jmolHtml(htmlText)

Allows you to pass arbitrary text, possibly containing HTML tags, directly to the page; sometimes this is more convenient than closing and reopening the script tags. The effect is exactly the same as:

</script>htmlText<script>

or

document.write(htmlText)

jmolBr

jmolBr()

Inserts a newline break into the page. It is equivalent to jmolHtml("<br />"), or </script><br /><script>, or document.write("<br />").

jmolScript

jmolScript(script, targetSuffix)

Use this if you want to construct your own user interface controls or to execute script based upon JavaScript events.

(This jmolScript function is also used internally to implement the UI controls above.)

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one the script will be applied. Default targetSuffix is "0" (i.e., the first applet in the page).

Special case: if "all" is used for targetSuffix, the script will be applied to all JmolApplets

Warning: please, be aware that, except for the first applet in the page, you must specify a targetSuffix here; setting jmolSetTarget does not apply to jmolScript, jmolScriptWait or jmolScriptWaitAsArray.

jmolScriptWait

jmolScriptWait(script, targetSuffix)

This function adds two improvements over jmolScript:

it waits until the script has completed running before returning control (thus stopping javascript from continuing with other tasks)
if assigned to a variable, it returns in that variable status messages that can be used to detect errors or diagnose problems.

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one the script will be applied. Default targetSuffix is "0" (i.e., the first applet in the page).

Examples:

result = jmolScriptWait("load myFile.mol") loads the model and puts into the "result" variable a string with the status messages, which for example contains, among other things, "FileNotFoundException" if myFile.mol file is not found.
result = jmolScriptWait("show orientation") puts into the "result" variable the instructions needed to restore the current orientation (although the returned string may need parsing to be useful as a command).

jmolScriptWaitAsArray

jmolScriptWaitAsArray(script, targetSuffix)

This function adds two improvements over jmolScript:

it waits until the script has completed running before returning control (thus stopping javascript from continuing with other tasks)
if assigned to a variable, it returns in that variable an array of status messages that can be used to detect errors or diagnose problems.

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one the script will be applied. Default targetSuffix is "0" (i.e., the first applet in the page).

See also jmolScriptWait above, which returns a single text string instead of an array. (Actually, it works by calling jmolScriptWaitAsArray and concatenating its array elements with newline characters.)

jmolCommandInput

jmolCommandInput(label, size, id, title)

Displays an empty one-line textbox followed by a button labeled with text label. When the user presses the button, any script written in the textbox will be executed on the applet. (Thus, this gives a sort of command-line console.)

If the page contains several Jmol applets, commands in the textbox will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

If no label is given, "Execute" will be used by default.

size is the width of the textbox (as number of characters; default is 60).

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

Advanced: In addition, the textbox + button will be included in a element that will have an HTML id of "span_" plus the given id, and an HTML title of the given title (optional).

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

jmolSaveOrientation

jmolSaveOrientation(id, targetSuffix)

Allows to save the current orientation of the model into an internal variable identified by id, so that it can be recovered later by calling jmolRestoreOrientation with the same id.

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one to act; default is "0" (i.e., the first applet in the page).

jmolRestoreOrientation

jmolRestoreOrientation(id, targetSuffix)

Allows to return the model to an orientation previously saved by using jmolSaveOrientation with the same id.

The reorientation is done instantaneously. For a timed reorientation, use jmolRestoreOrientationDelayed.

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one to act; default is "0" (i.e., the first applet in the page).

jmolRestoreOrientationDelayed

jmolRestoreOrientationDelayed(id, delay, targetSuffix)

Allows to return the model to an orientation previously saved by using jmolSaveOrientation with the same id.

The reorientation extends along delay seconds (default is 1 second).

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one to act; default is "0" (i.e., the first applet in the page).

Advanced Applet Scripting

jmolDebugAlert

jmolDebugAlert(enableAlerts)

Puts up alert boxes for debugging. Use carefully or you will get a lot of alerts. Explicitly pass in a false parameter to turn it off.

jmolSetLogLevel

jmolSetLogLevel(n)

Adjusts the level of messages shown in the console. n ranges from 0 (minimum of messages) to 5 (all messages).

jmolGetStatus

jmolGetStatus(strStatus, targetSuffix)

(...needs documentation)

When more than one JmolApplet is being displayed, targetSuffix is used to specify on which one to act (default is "0", i.e., the first applet in the page).

jmolSetTarget

jmolSetTarget(targetSuffix)

This specifies upon which JmolApplet the following user interface controls must act. It is only needed if you are displaying multiple applets on the same page and your jmolButton, jmolLink, jmolCheckbox, jmolRadioGroup, jmolMenu, jmolRadio controls are not sequentially following the instance of jmolApplet to which they must be associated.

All JmolApplets which are generated by the Jmol.js library receive an internal identifier, by default a sequential number starting from 0. So, to address the first and second applets on the page you must use jmolSetTarget(0) and jmolSetTarget(1).

Instead of leaving the default numbers, you are encouraged to provide your own suffixes in your calls to jmolApplet and hence use those suffixes in jmolSetTarget.

jmolRadio

jmolRadio(script, labelHtml, isChecked, separatorHtml, groupName, id, title)

First, try very hard to use jmolRadioGroup. If your layout does not allow you to do that, then use this to allocate individual radio buttons.

For description of script, labelHtml, isChecked, and separatorHtml parameters, see jmolRadioGroup command.

Radio buttons will be assigned to the group specified by groupName. In other words, linked radio buttons (those mutually exclusive in their checked state) will be those that share the same value of groupName.

If you don't want to use a groupName, all buttons will be assigned to the same group (with an automatically assigned name) until you call jmolStartNewRadioGroup to start a new group.

If the page contains several Jmol applets, commands in the script will be applied to the immediately previous applet, or to that specified by a previous jmolSetTarget command.

Advanced:

The radio button plus its label will have as their HTML id "span_" plus the given id, and as their HTML title, the given title (optional). In addition, the radio buttom itself will have the given id as its HTML id (optional).

The label will be surrounded by <label> tags; the effect is that clicking on the label text will have the same effect as clicking on the radio button itself.

jmolStartNewRadioGroup

jmolStartNewRadioGroup()

Do not use this unless you are working with multiple radio groups whose layout is so complicated that you cannot use jmolRadioGroup.

Read jmolRadio, above, for an explanation of how to use this function.

jmolSetCheckboxGroup

jmolSetCheckboxGroup(chkMaster, chkBoxes)

Starting with previously inserted checkboxes (using jmolCheckbox), this allows to establish a relation between one "parent" or "leader" checkbox and one or more "child" or "follower" checkboxes, according to these rules:

Whenever the leader is checked, all its followers get automatically checked.
Whenever the leader is unchecked, all its followers get automatically unchecked.
Whenever one of the followers is checked or unchecked, its siblings are examined; if all have the same state, the leader will be checked or unchecked accordingly.

chkMaster is the ID given to the checkbox that will act as leader. This ID may have been specified in its jmolCheckbox definition, or may be a number (if ID was not specified, sequential numeric IDs are assigned by default, starting from zero).

chkBoxes is one or more IDs or numbers (separated by commas), pointing to the checkboxes that will act as followers.

Any number of groups can be set in a page, with any number of component checkboxes, Nesting groups within other groups is also possible (i.e., a follower in one group may be the leader for an inner group).

Examples:

jmolSetCheckboxGroup(0, 1, 4)

Sets 1st checkbox in the page as leader, 2nd and 5th as followers.

jmolSetCheckboxGroup(4, 5, "chkH")

Sets 5th checkbox as leader, 6th and that identifed as "chkH" as followers.

jmolSetCheckboxGroup("chkH", "chkMethine", "chkMethyl")

Sets "chkH" checkbox as leader, those identifed as "chkMethine" and "chkMethyl" as followers.

jmolCheckBrowser

jmolCheckBrowser(action, urlOrMessage, nowOrOnClick)

Checks user's web browser for compliance and compatibility with Jmol. Also, allows to redirect the user to a custom message or web page whenever the explicit or automatic checking of browser fails.

action is a string which is one of "popup", "redirect", or "alert".

"popup" will bring up another browser window with the URL specified in urlOrMessage.
"redirect" will redirect the existing page to the URL specified in urlOrMessage.
"alert" will bring up a JavaScript alert message box with the text message specified in urlOrMessage.

nowOrOnClick is a string saying either "now" or "onClick" (default). It specifies when the browser check is to take place.

"now" specifies that the check is to take place immediately.
"onClick" indicates that the check is to take place the first time a control, such as a jmolButton(), is clicked.

If this call is not made, a default alert message is displayed when a user with a non-compliant browser clicks on a Jmol control.

jmolSetDocument

jmolSetDocument(doc)

By default, Jmol.js writes applets and controls to the page. Using this function allows other targets:

jmolSetDocument(win2.document) will write the applet and controls in another window (named "win2" in this example)
jmolSetDocument(0) or jmolSetDocument(false) will turn off writing the code as the page loads. The code will be retained and can be returned in a JavaScript variable, e.g.:

var myApplet = jmolApplet(...)

var myControls = jmolRadioGroup(...)

variables which can later be used to write a page or to write into a div, using JavaScript.

jmolSetAppletWindow

jmolSetAppletWindow(targetWindow)

Whenever a Jmol.js command is given that requires interaction with the applet, the applet object must first be found. In order to do this, one or more windows (or document "frames" if employed) must be checked. By default, checking for the existence of the applet is carried out first in the current window, then in its child frames, and finally in the "top" frame and any of its children. While this should be successful, in certain circumstances it may be preferable to explicitly identify which window to investigate first. This is done by using the jmolSetAppletWindow() command. The targetWindow parameter must be a window (or frame) object.

jmolAppletInline

jmolAppletInline(size, inlineModel, script, nameSuffix)

Creates an instance of the JmolApplet, but passes to it the contents of the molecular model rather than a file name or URL. You probably do not want to use this, unless you are pulling your molecular model data from a database.

script and nameSuffix work as in jmolApplet.

See also the note at the end of jmolApplet regarding the use of commands right after the applet call.

jmolLoadInline

jmolLoadInline(model, targetSuffix)

Used in database applications where the molecular model is available as a string. This directly loads model data into the applet. Note that this is not the file name ... it is the contents of the file.

model can also be an array of molecular models (between brackets and separated by commas), even in different file formats.

targetSuffix works as in jmolScript.

Warning: please, be aware that, except for the first applet in the page, you must specify a targetSuffix; setting jmolSetTarget does not apply to jmolLoadInline.

jmolLoadInlineScript

jmolLoadInlineScript(model, script, targetSuffix)

Similar to jmolLoadInline, but also allows to execute a script after the model has loaded.

script and targetSuffix work as in jmolScript.

Warning: please, be aware that, except for the first applet in the page, you must specify a targetSuffix; setting jmolSetTarget does not apply to jmolLoadInlineScript.

jmolSetCallback

jmolSetCallback("callbackName", "functionName")

Sets which JavaScript function to be called by Jmol for the specified callback type, as listed below.

functionName must be enclosed in double quotes. In each case, several parameters are returned and passed to the function:

the first parameter returned is the applet HTML name (usually "jmolApplet0");
the second parameter holds the information;
additional parameters are returned only in the case of some of the callbacks (see below), and hold additional information.

Please, note that all these parameters are returned in the form of Java strings, and as a general rule it is safer to convert them into JavaScript strings before using them within the function. This can be done in this way:

function functionName(a,b,c,d) {
  var aa = " + a;
  var bb = " + b;
  var cc = " + c;
  var dd = " + d;
  // here go desired actions, using  aa, bb, cc and dd instead of a, b, c, d
}

Special case: if functionName is alert, then only the second parameter is sent to the user via a JavaScript alert() call, and no additional function on the webpage is necessary.

jmolSetCallback must be invoked before jmolApplet. For setting callback functions anytime after Jmol applet loading, use the set animFrameCallback, set hoverCallback, etc. script commands [see details on Interactive Scripting Documentation]. For canceling callback detection, use set animFrameCallback none etc.

Callback types (values of callbackName) are:

animFrameCallback

Called: when the frame is changed. (Applicable to multi-model files and to multiple files loaded.)

Returned 2nd to 9th parameters:

The current frame index number (starting with 0)
The current file number (starting with 1)
The current model number within the current file (starting with 1)
The first frame of the animation range, expressed as fileNo x 1000000 + modelNo
The last frame of the animation range, expressed as fileNo x 1000000 + modelNo
0 (animation is off) or 1 (animation is on)
The current animation direction, either 1 or -1
The current direction, either 1 (forward) or -1 (reverse)

Note: Note that the frame index number is not the number that one would use in the "frame" script command. Frame index 0 is always the first frame, 1 the next, etc. If multiple files have been loaded, the third frame in the first file has index 2 but is accessed in scripts by "frame 1003" or "frame 1.3".

appletReadyCallback

Called: when the applet has finished loading, and also when it is destroyed (this may include reloading the page in the browser). The callback is fired after any script included in the jmolApplet() call has been executed.

Returned 2nd parameter: the applet HTML name, followed by 2 underscores, the unique syncID of the applet, and 2 underscores. Example: jmolApplet0__2810172796629116__

Returned 3rd parameter: true (if the applet was loaded) or false (if the applet was destroyed).

atomMovedCallback

Called: when any atoms are moved, either by script or by user action.

Returned 2nd parameter: BitSet of atoms moved.

echoCallback

Called: when an echo command is issued. If an echoCallback function is not defined, these messages go to the messageCallback function.

Returned 2nd parameter: the same text as the echo.

evalCallback

(Advanced) See the scripting doc.

hoverCallback

Called: when the user hovers over an atom.

Returned 2nd parameter: a string that depends upon the setting of the hover label for the hovered atom (see below).

Returned 3rd parameter: atom index, starting with 0.

If the operation of the function includes a jmolScript command that sets the hover text, then the applet page can control on the fly what is displayed whenever any atom is hovered over. For example:

function myfunc(a,mess) {
   var msg;
   var s = "" + mess; // convert the 2nd parameter to a JavaScript string
   if (s.charAt(0) == 'C') {
     msg = "yes, that is a carbon.";
   } else {
     msg = "no, that is not a carbon. The carbons are grey.";
   }
   jmolScript('hover "'+msg+'"');
}

sets the message that will be displayed depending upon the atom hovered over.

language

This is special: it is not called by an event, only by design, and does not return anything. Instead, it changes the interface language for the applet pop-up menu and messages in the console. It must be called before jmolApplet. The same functionality is available after the applet has been loaded, by means of the scripting language (e.g. language = "de"), as well as from the pop-up menu itself.

The first parameter must be "language" and the second, the two-letter code (or 2+2 letter code) of the language wanted (provided that locale has been built into Jmol).

Examples:

jmolSetCallback("language", "de") (German)
jmolSetCallback("language", "en") (English)
jmolSetCallback("language", "es") (Spanish)
jmolSetCallback("language", "fr") (French)
jmolSetCallback("language", "pt_BR") (Brazilian Portuguese)

loadStructCallback

Called: upon successful file loading.

Returned 2nd parameter: the URL of the loaded file (full path+filename).

Returned 3rd parameter: the filename of the loaded file (without the path).

Returned 4th parameter: the internal title of the model in the loaded file.

Returned 5th parameter: any error messages generated.

Returned 6th parameter: a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed.

Returned 7th parameter: a text string with the frame number prior to loading the current model, in file.model syntax (for example, "3.1" or "1.1 - 3.31" if a whole range of models was framed).

Returned 8th parameter: a text string with the last frame number after loading the current model, in file.model syntax.

Note: When multiple files are loaded with the same load command, only data for the last-loaded file is returned.

measureCallback

Called: when a measurement is made by the user. If a measureCallback function is not defined, these messages go to the messageCallback function.

Returned 2nd parameter: text indicating the status of measurements.

messageCallback

Called: whenever a Jmol status message is generated.

Returned 2nd parameter: the status message.

Note: Messages are generated:

by the "message" script command
by the "echo" script command (even if no message is displayed)
by the "history", "show", and "getProperty" script commands
by the "connect" script command
by the "set xxxxCallback" script command, if "xxxx" is not one of "animFrame", "hover", "loadStruct", "message", or "pick"
by user measuring, provided "set picking measure" has been issued
when the user has picked the first atom, provided "set picking spin" has been issued
whenever the number of selected atoms is changed
due to errors during the execution of various commands, including "pmesh", "set"
upon script completion ("Script completed") unless there is a compiler error ("script compiler ERROR:...")
upon script execution error ("script ERROR:..."), provided there is no compiler error
at a variety of points, provided either "set debugScript" or "set loglevel 5" has been issued.

(The distinction between compiler error and execution error is subtle. With a compiler error, no portion of the script was executed; with an execution error, the script has been executed up to the point of the error. Only a portion of the allowed command syntax is checked during compilation.)

minimizationCallback

Called: at each iteration of a minimization.

Returned 2nd parameter: text indicating the current status of a currently running minimization: either starting, running, or done.

Returned 3rd parameter: the number of the iteration.

Returned 4th parameter: a number with the value of energy (E) at that step.

Returned 5th parameter: a number with the decrease in energy (dE) at that step.

pickCallback

Called: when the user clicks an atom.

Returned 2nd parameter: atom id, atom number, and xyz coordinates in the form:

C6 #6 -0.30683374 -1.6836332 -0.716934

Returned 3rd parameter: atom index, starting with 0.

resizeCallback

Called: when the applet size changes.

Returned 2nd parameter: width (in pixels).

Returned 3rd parameter: height (in pixels).

scriptCallback

Called: when a script is being executed.

Sends messages indicating the status of script execution. Line-by-line script commands are sent if set debugScript true has been issued.

If a scriptCallback function is not defined, these messages go to the messageCallback function.

statusForm, statusText, statusTextarea

Called: anytime a message for the document status line is sent.

Returned 2nd parameter: status message.

Note: Not actually function callbacks, these options allow for writing status information into text and textarea elements on the page. Before jmolApplet, use

jmolSetCallback("statusForm", "some_form_name")
jmolSetCallback("statusText", "some_text_name")

or

jmolSetCallback("statusForm", "some_form_name")
jmolSetCallback("statusTextarea", "some_textarea_name")

The difference is that statusText replaces that element's value with the message and statusTextarea appends the message to the existing value. So with a typical successful script, statusText replaces the text with "Jmol script terminated". If there is an error, the text area will end up blank. In contrast, statusTextarea appends messages, so a full report is delivered there.

(These aren't well tested. Maybe useful more for debugging than anything else. See http://www.stolaf.edu/academics/chemapps/jmol/docs/examples-11/simple2.htm for an example of their use.)

syncCallback

Called: when a synchronization message is sent from one applet to another.

The JavaScript function may modify or cancel the synchronization message. If the called function returns "" or 0, the synchronization is canceled; any other string is substituted for the script and sent to the other currently synchronized applets.

jmolAppletAddParam

jmolAppletAddParam(appletCode, name, value)

Adds parameter data to an applet definition HTML string previously created using:

jmolSetDocument(0);
var appletCode = jmolApplet(....);
appletCode = jmolAppletAddParam(appletCode, name, value);

for later writing to the web page using

document.write(appletCode)

jmolEvaluate

jmolEvaluate(molecularMath, targetSuffix)

Allows to extract to JavaScript (e.g. to a variable) information from a variable set in the Jmol scripting language, a Jmol math expression, or some model information. Examples:

alert( jmolEvaluate("a") );
 // Displays the value of the 'a' variable if set in Jmol script.
alert( jmolEvaluate("{*}.xyz") );
 // Displays the coordinates of the geometric center of the model.
alert( jmolEvaluate("{*}.length") );
 // Displays the total number of atoms in the model.
alert( jmolEvaluate("{carbon}.bonds.length.min") );
 // Displays the minimum bond length between carbon atoms.
alert( jmolEvaluate("_atomPicked") );
 // Displays the index of the atom that was most recently picked.

jmolGetPropertyAsArray

jmolGetPropertyAsArray(sKey, sValue, targetSuffix)

Returns applet information in the form of a JavaScript array, when applicable, and a JavaScript string when not. One example:

var atoms = jmolGetPropertyAsArray("atomInfo","all");
var atom1 = atoms[0];
var x = atom1.x;
var info = atom1.info;

jmolGetPropertyAsString

jmolGetPropertyAsString(sKey, sValue, targetSuffix)

Returns data as per jmolGetPropertyAsArray, but always as a JavaScript string. In the case of arrayed data, this string is tab/line-delimited for easier reading.

jmolGetPropertyAsJSON

jmolGetPropertyAsJSON(sKey, sValue, targetSuffix)

Returns data as per jmolGetPropertyAsArray, but always as a JavaScript string in JavaScript Object Notation. This string can then be surrounded by parentheses and evaluated to create array content. For example:

var info = jmolGetPropertyAsJSON("filename")

sets the info variable to be

{"filename": "file:/C:/data/caffeine.xyz"}

Then

var Info = eval("(" + info + ")")

results in a new JavaScript array Info having the element Info.filename with the value "file:/C:/data/caffeine.xyz"

jmolGetPropertyAsJavaObject

jmolGetPropertyAsJavaObject(sKey, sValue, targetSuffix)

Returns the property as a Java (not JavaScript) object. This function is for advanced users only and is not generally recommended, as it delivers a pointer to the Java object itself, not a copy of it. This pointer may or may not be valid indefinitely and may or may not be properly garbage-collected by all browsers. Not tested extensively on a variety of platforms. The principal use of this function is for access to public Viewer methods that are not generally available via the applet interface. For example:

var viewer = jmolGetPropertyAsJavaObject("jmolViewer")
var radius = viewer.getRotationRadius()

Most of these public methods are listed in http://jmol.svn.sourceforge.net/viewvc/jmol/trunk/Jmol/src/org/jmol/api/JmolViewer.java?view=markup

jmolDecodeJSON

jmolDecodeJSON(s)

Decodes a JavaScript Object Notation string into a JavaScript string that can be read by humans or executed as JavaScript. For example:

var info = jmolGetPropertyAsJSON("atominfo", "atomno=1")
alert(jmolDecodeJSON(info))

displays:

atominfo=new Array()
atominfo[0]=new Array()
atominfo[0].element="hydrogen"
atominfo[0].visible=true
atominfo[0].model=1
atominfo[0].radius=0.5
atominfo[0].visibilityFlags=13
atominfo[0].clickabilityFlags=12
atominfo[0].bondCount=1
atominfo[0].atomno=1
atominfo[0].elemno=1
atominfo[0].z=0.5733036
atominfo[0].y=-1.1272367
atominfo[0].x=-3.380413
atominfo[0].partialCharge=0
atominfo[0].sym="H"
atominfo[0].colix=-32767
atominfo[0].spacefill=60
atominfo[0].color="ffffff"
atominfo[0].info="H1 #1"
atominfo[0]._ipt=0
atominfo[0].formalCharge=0

jmolScriptEcho

jmolScriptEcho(script, targetSuffix)

Returns a newline-separated list, in reverse order, of all echos from a script, associated to the specified JmolApplet.

jmolScriptMessage

jmolScriptMessage(script, targetSuffix)

Returns a newline-separated list, in reverse order, of all messages from a script, associated to the specified JmolApplet, ending with Script completed\n.

Cascading Style Sheet support

jmolSetAppletCssClass

jmolSetAppletCssClass(appletCssClass)

Set the cascading style sheet class that is to be used within the applet tags generated by jmolApplet and jmolAppletInline.

jmolSetButtonCssClass

jmolSetButtonCssClass(buttonCssClass)

Set the cascading style sheet class that is to be used within the input tags generated by jmolButton.

jmolSetCheckboxCssClass

jmolSetCheckboxCssClass(checkboxCssClass)

Set the cascading style sheet class that is to be used within the input tags generated by jmolCheckbox.

jmolSetRadioCssClass

jmolSetRadioCssClass(radioCssClass)

Set the cascading style sheet class that is to be used within the input tags generated by jmolRadioGroup and jmolRadio.

jmolSetLinkCssClass

jmolSetLinkCssClass(linkCssClass)

Set the cascading style sheet class that is to be used within the a tags generated by jmolLink.

jmolSetMenuCssClass

jmolSetMenuCssClass(menuCssClass)

Set the cascading style sheet class that is to be used within the select tags generated by jmolMenu.

Contributors

AngelHerraez

@@ Line 3: / Line 3: @@
 = Jmol.js JavaScript Library =
+<div style="text-align:center;background-color:#FFFF80;">
 '''Please, note that the use of this library is deprecated and no longer recommended. Documentation is kept here only for historical reasons, and as a possible reference for those still using the Jmol2.js adapter library.'''
+</div>
 This documentation used to be available at Jmol website,
-http://jmol.org/jslibrary/
+<nowiki>http://jmol.org/jslibrary/</nowiki>
 == Basic Scripting Commands ==

Difference between revisions of "Jmol JavaScript Object/Legacy/Jmol Js"

Revision as of 20:18, 26 November 2019

Contents

Jmol.js JavaScript Library

Basic Scripting Commands

jmolInitialize

Using signed applet or custom applets

jmolApplet

jmolButton

jmolLink

jmolCheckbox

jmolRadioGroup

jmolMenu

Intermediate Scripting Commands

jmolSetAppletColor

jmolResizeApplet

jmolHtml

jmolBr

jmolScript

jmolScriptWait

jmolScriptWaitAsArray

jmolCommandInput

jmolSaveOrientation

jmolRestoreOrientation

jmolRestoreOrientationDelayed

Advanced Applet Scripting

jmolDebugAlert

jmolSetLogLevel

jmolGetStatus

jmolSetTarget

jmolRadio

jmolStartNewRadioGroup

jmolSetCheckboxGroup

jmolCheckBrowser

jmolSetDocument

jmolSetAppletWindow

jmolAppletInline

jmolLoadInline

jmolLoadInlineScript

jmolSetCallback

animFrameCallback

appletReadyCallback

atomMovedCallback

echoCallback

evalCallback

hoverCallback

language

loadStructCallback

measureCallback

messageCallback

minimizationCallback

pickCallback

resizeCallback

scriptCallback

statusForm, statusText, statusTextarea

syncCallback

jmolAppletAddParam

jmolEvaluate

jmolGetPropertyAsArray

jmolGetPropertyAsString

jmolGetPropertyAsJSON

jmolGetPropertyAsJavaObject

jmolDecodeJSON

jmolScriptEcho

jmolScriptMessage

Cascading Style Sheet support

jmolSetAppletCssClass

jmolSetButtonCssClass

jmolSetCheckboxCssClass

jmolSetRadioCssClass

jmolSetLinkCssClass

jmolSetMenuCssClass

Contributors

Navigation menu

Search