Jmol JavaScript Object
This page is under construction.
WORK IN PROGRESS -- REMODELLING AND REWRITING OF Jmol-JSO + JSmol PAGE
Contents
Jmol-JSO
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 non-Java visualization resource, like JSmol or a third-party resource (using WebGL and/or HTML5), or even an image, depending on client's platform resources.
Using Jmol-JSO, a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using a Jmol applet surrogate (such as JSmol, GLmol, ChemDoodle, or just an image) while still implementing JmolApplet on traditional platforms. Compromises will have to be made, because other resources do not have the scripting power of Jmol and JSmol. However, the wide variety of options available allows a subset of Jmol functionality on all such devices, and there should be no need to ever see a message "Sorry, you don't have Java installed...."
Jmol-JSO also integrates facilities for direct, behind-the-scenes access to public databases such as the RCSB PDB database, the National Cancer Institute CACTVS server, and PubChem, even when the user's platform does not allow the Jmol Java applet.
In addition, Jmol-JSO allows easy interaction with
- the JSpecView applet, allowing to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra (see more details)
- the JME applet, so 3D models can be generated by a page visitor using simple chemical 2D drawing.
Jmol-JSO is fully compatible with jQuery, creating the single global Jmol
object. The library has been W3C and XHTML validated.
Representative differences with Jmol.js
JSmol
...
Installation
Jmol-JSO is generated with a suite of JavaScript libraries that replace Jmol.js. There are also a set of files that implement JSmol, the JavaScript-only alternative to Jmol. Finally, there are the Java files for the classic JmolApplet, which remain the same.
- 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 up to date. Please file a bug report if you find a problem.
JSmol releases may be obtained at the JSmol Project page, or the latest development set of files from St. Olaf.
The download contains these files and folders:
- Major files:
- JSmol.min.js The only library that needs to be called explictly; it will take care of calling any of the other files as needed. (This includes a set of files minimized using the Google Closure Compiler)
- jsmol.php A utility that allows some server-side operations (...more details to be included here...). By default, JSmol will try to use a copy of this file at the St.Olaf server, but you need to put a copy in your own server in order to get full functionality.
- java The files for the JmolApplet, the same that have been used for Jmol in previous versions
- (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.
- js The suite of JavaScript libraries needed for building the Jmol-JSO object (but most of these files are already included in packed form within JSmol.min.js, see below):
- JSmol.js
- JSmolCore.js
- JSmolApplet.js
- JSmolApi.js
- JSmoljQuery.js
- j2sjmolfull.js
- JSmolControls.js Required only if any buttons or links or other input methods will be used.
- JSmolJSV.js Needed only for using the JSpecView applet
- JSmolGLmol.js Needed only for using the GLmol surrogate
- JSmolThree.js Needed only for using the GLmol surrogate
- j2s The suite of JavaScript libraries needed for JSmol, which is the non-Java, HTML5-only surrogate with full Jmol functionality
- Some accessory files, included for your convenience but not required for functionality:
- make and test are not generally needed.
In summary:
- For pages that use HTML5-only JSmol, you just need JSmol.min.js and j2s (A total of 12.6 MB, but only those parts actually needed will be downloaded to the client computer).
- For pages that use only the Jmol Java applet, you just need JSmol.min.js and java (A total of 7.9 MB, but may be reduced to 2.2 MB for a single set of signed or unsigned applet files, of which only those parts actually needed will be downloaded to the client computer).
- js is only important if you want to use the the GLmol surrogate, because the WebGL library is not included in JSmol.min.js. Specifically, you need js/JSmolGLmol.js and js/JSmolThree.js (which are not minimized).
Initialization
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>
Optional components
- Integration with JME, a Java-based editor to draw 2D chemical structures (Peter Ertl's Java Molecular Editor)
- Integration with JSpecView, a Java viewer for spectral data.
- GLmol option to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems) (does not use Java)
- ChemDoodle option to render the 3D model using ChemDoodle (does not use Java)
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. The principal 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/jsmol/jsmol.php", src: null, use: "Java noWebGL noHTML5 noImage", width: 300 };
Detailed explanation of the parameters of the Info
variable.
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
Syntax: Jmol.getApplet = function(id, Info, checkOnly)
This function creates the JavaScript Object that keeps track of the Jmol applet (or the JSmol surrogate if a non-Java option is active). It should be assigned to a variable with the same name as the id. For example:
myJmol = Jmol.getApplet("myJmol", 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, a JSmol canvas, an image, a GLmol canvas, etc.
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)
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 giventitle
. - 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, usingJmol.setDocument(0)
, appending the HTML to a growing string using the control-specific functions, then setting the code in a predefineddiv
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>')
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)
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)
Methods specific to optional components
Contributors
AngelHerraez, Hansonr, Hansonrstolaf, Cudo29, Ceroni, Ppillot