Jmol JavaScript Object/Functions

Functions for Jmol JavaScript Object

Parent page: Jmol JavaScript Object.

Functions for creation or display of Jmol Objects

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

getApplet

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

This function creates in JavaScript space of the webpage the Jmol object (either a Jmol/Java applet or a JSmol object). For example:

Jmol.getApplet("myJmol", Info);

The above example will create a myJmol variable that holds the Jmol Object, and the object will be inserted in the page (unless Jmol.setDocument() has been set false, see below).

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

getTMApplet

This function creates and inserts the lightweight variety of JSmol object. For example:

Jmol.getTMApplet("myJmol", Info);

Note: the reason for the name is that this lightweight alternative was inspired on a viewer named TwirlyMol.

getAppletHtml

Definition: Jmol.getAppletHtml = function(JmolObject)

or: Jmol.getAppletHtml = function(id, Info)

Useful for inserting the Jmol object code into the page, either after page has loaded or in the case when the object was generated and stored in a variable, e.g. after Jmol.setDocument(0). It is particularly useful with .innerHTML inside window.onload or in a function fired by user action (or the jQuery equivalents .html() and $(document).ready). Some examples:

window.onload = function(){
  Jmol.setDocument(0);
  Jmol.getApplet("jmol1", Info); // creates the object but does not insert it
  Jmol.getApplet("jmol2", Info);
  [...] // other actions, that may affect the Jmol objects
  // now, let's insert the objects in the page:
  document.getElementById("place1").innerHTML = Jmol.getAppletHtml(jmol1);
  document.getElementById("place2").innerHTML = Jmol.getAppletHtml(jmol2);
});

jQuery equivalent syntax:

$(document).ready(function(){
  Jmol.setDocument(0);
  Jmol.getApplet("jmol1", Info); // creates the object but does not insert it
  Jmol.getApplet("jmol2", Info);
  [...] // other actions, that may affect the Jmol objects
  // now, let's insert the objects in the page:
  $("#place1").html(Jmol.getAppletHtml(jmol1));
  $("#place2").html(Jmol.getAppletHtml(jmol2));
});

Or a simpler syntax that creates the object and inserts it at the same time:

window.onload = function(){
  document.getElementById("place1").innerHTML = Jmol.getAppletHtml("jmol1", Info);
  document.getElementById("place2").innerHTML = Jmol.getAppletHtml("jmol2", Info);
});

See also under Jmol.setDocument()

getVersion

Definition: Jmol.getVersion = function()

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

Example:

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

resizeApplet

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

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

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

Examples:

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

setAppletSync

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

setDocument

Definition: Jmol.setDocument = function(doc)

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

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

Example:

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

or, using jQuery syntax;

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

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

setGrabberOptions

Definition: Jmol.setGrabberOptions = function(options)

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

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

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

showInfo

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

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

The tf parameter is a true or false flag.

setInfo

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

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

setXHTML

Definition: Jmol.setXHTML = function(id)

Indicates id of the DOM node into which the Jmol object will be inserted, following XHTML format when creating page elements. Largely untested.

Example:

<!doctype html>
<head>
<meta charset="UTF-8" />
<title>test XHTML</title>
<script type="text/javascript" src="JSmol.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
  var Info = {
    height: 300,
    width: 300,
    j2sPath: "j2s",
    use: "HTML5"
  };
  Jmol.setXHTML('myContainer');
  Jmol.getApplet(myJmol, Info);
});
</script>
</head>
<body>
<p>Some text</p>
<div id="myContainer"></div>
<p>Some more text</p>
</body>
</html>

Functions for creating controls

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

The first parameter for nearly all of these functions, JmolObject, must be a reference to the object 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 content.

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

Example:

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

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

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

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

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

Advanced:

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

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

jmolCheckbox

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

Inserts a checkbox into the page, followed immediately by labelHtml.

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

scriptWhenUnchecked is run when the user unchecks the checkbox.

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.

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

Example:

Jmol.jmolCheckbox(myJmol,"spacefill on","spacefill off","toggle display as spheres");

setCheckboxGroup

Definition: Jmol.setCheckboxGroup(chkMaster,chkBoxes)

Starting with previously inserted checkboxes (using Jmol.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.

The Jmol scripts associated to each checkbox when it was inserted/defined will be executed when its state changes due to action on another checkbox.

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

chkBoxes is an array of one or more IDs or numbers, 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).

jmolCommandInput

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

jmolLink

Definition: Jmol.jmolLink(JmolObject, 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.

Example:

Jmol.jmolLink(myJmol,"load adenine.mol","adenine");

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

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

jmolRadio

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

Inserts a single radio button into the page, followed immediately by labelHtml.

script is run when the user checks the radio button.

labelHtml is written to the page right after the radio button. Note that it must be a text string (if you wanted to use a number, wrap it in quotes).

isChecked should be set to a non-false value (e.g.: true) if you want the radio button to be marked upon page loading (default: not checked).

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

separatorHtml is used to specify HTML code that should be placed after the radio button and its labelHtml. 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 a non-breaking space.

id will be set as the HTML id. If not provided, a default name is made up automatically.

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

Example:

Jmol.jmolRadio(myJmol,"spacefill 23%; wireframe 0.15;","ball and stick",true);

jmolRadioGroup

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

Inserts a group of mutually-exclusive radio buttons into the page.

arrayOfRadioButtons is usually specified using the JavaScript square brackets [ entryA, entryB, ... ] notation. Each entry is generally another array which contains a script, a label (text displayed in the page after the radio button), 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.

separatorHtml is used to specify HTML code that should be placed after each radio button and its label, but before the next 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 a non-breaking space.

Radio buttons will all belong to a group with an HTML name of groupName. If you don't specify one, it will be automatically made up.

The whole group of radio buttons will be included in a <span> element that will have as its HTML id the value of id or, if this is not given, the value of groupName. 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. 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.

Example:

 var r = [
    ["spacefill 23%; wireframe 0.15;","ball and stick",true],
    ["spacefill off; wireframe 0.15;","sticks"],
    ["spacefill on; wireframe off;","spheres"]
 ];
 Jmol.jmolRadioGroup(myJmol, r, "<br>", "atomstyle");

Functions that insert HTML

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

Again, all these functions must be applied to the unique Jmol constructor (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. Example:

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

Functions that set CSS rules

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

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

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

setAppletCss

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

setButtonCss

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

setCheckboxCss

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

setLinkCss

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

setMenuCss

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

setRadioCss

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

Functions that interact with a running Jmol Object

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

evaluateVar

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:

Definition: Jmol.evaluateVar = function(applet,molecularMath)

Examples:

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

Note: An older version of this method, Jmol.evaluate(), is deprecated, as it only returns String, Integer, or Float values.

getPropertyAsArray

Returns applet information in the form of a JavaScript array, when applicable, or other appropriate JavaScript variable type such as boolean, number, or string.

Definition: Jmol.getPropertyAsArray = function(JmolObject,sKey,sValue)

Examples:

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

getPropertyAsJavaObject

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. The principal use of this function is for access to public Viewer methods that are not generally available via the applet interface.

Note that even the HTML5 version of JSmol returns objects that for all practical purposes are "Java Objects" using this method. The only difference is that the JavaScript implementations have no aspect of "private" or "public" -- all methods are effectively public.

Definition: Jmol.getPropertyAsJavaObject = function(JmolObject,sKey,sValue)

Example:

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

Many of these public methods are listed in JmolViewer.java

getPropertyAsJSON

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.

Definition: Jmol.getPropertyAsJSON = function(JmolObject,sKey,sValue)

Example:

var info = Jmol.getPropertyAsJSON(myJmol, "filename") // {"filename": "file:/C:/data/caffeine.xyz"}

getPropertyAsString

Returns data as per jmolGetPropertyAsArray, but always as a JavaScript string. In the case of arrayed data, this string is formatted for easier reading.

Definition: Jmol.getPropertyAsString = function(JmolObject,sKey,sValue)

Examples:

var s = Jmol.getPropertyAsString(myJmol, 'stateInfo');
img.src = 'data:image/jpeg;base64,' + Jmol.getPropertyAsString(myJmol, 'image');

script

Runs a Jmol script asynchronously, meaning the script is put into a queue and most likely not processed before the function call is returned. This call can be made any time after applet creation; one does not have to wait until the applet is ready for receiving scripts (as was the case with Jmol/Java when Jmol.js was used).

Definition: Jmol.script = function(JmolObject, myScript)

myScript (a text string containing one or several Jmol commands) is placed on the script queue.

Examples:

Jmol.script(myJmol, "spacefill off; wireframe 0.3;");
Jmol.script(myJmol, "script someScript.spt;");

scriptEcho

Runs a script synchronously, returning the text that might have gone to the console.

Definition: Jmol.scriptEcho = function(JmolObject, myScript)

Example:

alert(Jmol.scriptEcho(myJmol, "show file")) 

scriptWait

Runs a script synchronously, similarly to scriptEcho(), but returns a string including messages. NOTE: When using JSmol/Java do not call this method from a callback directly, as it may result in Java thread lock, causing the entire browser to hang. Consider using evaluateVar() instead. If you need to call Jmol.scriptWait from within a callback, use the following syntax:

function myCallback(app,param1,param2,....) {

 setTimeout(function() {
   ...your callback code here...
 },10);

}

Definition: Jmol.scriptWait = function(JmolObject, myScript)

Example:

Jmol.scriptWait(myJmol, "background red")

returns:

2,scriptStatus,0,script 15 started
3,scriptStatus,0,script ERROR: command expected
----
        >> backgroundred <<
4,scriptStatus,0,Script completed
5,scriptTerminated,1,Jmol script terminated successfully
7,scriptTerminated,1,Jmol script terminated unsuccessfully: Jmol script terminated
1,scriptStarted,15,backgroundred
6,scriptError,0,Jmol script terminated

Deprecated, unnecessary or not recommended

The following methods are retained in Jmol-JSO since they were available in Jmol.js, but are not recommended. Most have simple scriptable alternatives.

getInfo

Jmol.getInfo = function(JmolObject)

Use instead Jmol.getPropertyAsArray(myJmol, "appletInfo")

getStatus

Jmol.getStatus = function(JmolObject, strStatus)

Deprecated.

loadFile

Jmol.loadFile = function(JmolObject, fileName, params)

Use instead Jmol.script(myJmol, "load '" + fileName + "'....")

say

Jmol.say = function(msg)

Use just alert(msg)

saveOrientation

Jmol.saveOrientation = function(JmolObject, id)

Use instead Jmol.script(myJmol, "saveOrientation " + id)

restoreOrientation

Jmol.restoreOrientation = function(JmolObject, id)

Use instead Jmol.script(myJmol, "restore orientation " + id)

restoreOrientationDelayed

Jmol.restoreOrientationDelayed = function(JmolObject, id, delay)

Use instead Jmol.script(myJmol, "delay " + delay + "; restore orientation " + id)

scriptMessage

Jmol.scriptMessage = function(JmolObject, script)

Use instead Jmol.scriptWait(....)

scriptWaitAsArray

Jmol.scriptWaitAsArray = function(JmolObject, script)

Deprecated.

scriptWaitOutput

Jmol.scriptWaitOutput = function(JmolObject, script)

Same as Jmol.scriptWait(); deprecated; see Jmol.scriptEcho()

search

Jmol.search = function(JmolObject, query, script)

Use instead Jmol.script(myJmol, "load $caffeine") for example.

Methods specific to optional components

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

Contributors

AngelHerraez, Hansonr, Cudo29