Help translating this website. Contact jmol-users@lists.sourceforge.net.

Jmol.js JavaScript Library

Information on this page relates to the upcoming release Jmol v10 release that is currently in beta test.

Jmol.js is a JavaScript library that can be used to simplify development of web pages that include the JmolApplet.

Why should you use Jmol.js?
Sample HTML page using Jmol.js
General Recommendations
Basic Scripting Commands
     jmolInitialize
     jmolApplet
     jmolButton
     jmolCheckbox
     jmolRadioGroup
     jmolLink
     jmolMenu
Intermediate Scripting Commands
     jmolSetAppletColor
     jmolHtml
     jmolBr
     jmolAppletInline
     jmolLoadInline
     jmolScript
Advanced Applet Scripting
     jmolDebugAlert
     jmolSetTarget
     jmolRadio
     jmolStartNewRadioGroup
     jmolCheckBrowser
Cascading Style Sheet support
     jmolSetAppletCssClass
     jmolSetButtonCssClass
     jmolSetCheckboxCssClass
     jmolSetRadioCssClass
     jmolSetLinkCssClass
     jmolSetMenuCssClass

Why should you use Jmol.js?

We strongly recommend that you use Jmol.js to build your web pages. It automates the generation of many HTML tag sequences, thereby making the code simpler, easier to understand, and less error-prone.

The Jmol.js library should work well with most web browsers released this century. In addition, on Win32 platforms it generally works fine with the Netscape 4.* series of browsers (from the previous century).

Note that on Mac OS X, Internet Explorer is not supported because it does not provide LiveConnect communications between JavaScript and Java applets. Also note that the Mozilla family of browsers (including FireFox and Camino) must be configured to use Java 1.4.2 using javaplugin.sourceforge.net

There are a few circumstances under which you may choose not to use the Jmol.js library. For example, you may be building an advanced web server application using server-side HTML generation, such as PHP, JSP, ASP, CGI, etc. In this case, it might be appropriate to generate the HTML code directly on your server rather than use the Jmol.js library. If you are unsure, then use the Jmol.js library.

Sample HTML page using Jmol.js

Click here to open a new browser window that shows the sample page generated by the following html source code

<html>
  <head>
    <title>Simple example</title>
    <script src="../jmol/Jmol.js"></script>
  </head>
  <body>
    <script>
      jmolInitialize("../jmol"); // REQUIRED
      jmolApplet(200, "load caffeine.xyz");
    </script>
  </body>
</html>

Click here to see a slightly more complicated example that demonstrates the the different types of user inteface controls that can be generated using the Jmol.js library.

<html>
  <head>
    <title>UI Controls example</title>
    <script src="../jmol/Jmol.js"></script> <!-- REQUIRED -->
  </head>
  <body>
    <form> <!-- form tags must enclose button/checkbox/radio/menu controls -->
      <script>
        jmolInitialize("../jmol"); // REQUIRED
        jmolSetAppletColor("skyblue"); // if you don't want black

	// 200x200 + file from another directory
	jmolApplet(200, "load ../jssample0/caffeine.xyz");
	jmolBr();
	// a radio group
	jmolHtml("atoms ");
	jmolRadioGroup([
          ["spacefill off",  "off"],
	  ["spacefill 20%",  "20%", "checked"],
	  ["spacefill 100%", "100%"]
	]);
	jmolBr();
	// a button
	jmolButton("reset", "Reset to original orientation");
	jmolBr();
	// a checkbox
	jmolCheckbox("spin on", "spin off", "spin");
	jmolBr();
	// a link
	jmolLink("move 360 0 0 0 0 0 0 0 2", "Rotate once about the x axis");
	jmolBr();
	// a menu
	jmolMenu([
	"background white",
	["background skyblue", null, "selected"],
	"background yellow",
	"background salmon",
	"background palegreen",
	"background black"
	]);
      </script>
    </form>
  </body>
</html>

General Recommendations

There is one directory on your web server that contains Jmol.js, JmolApplet.jar, and any other jmol-specific files. For the purposes of this discussion we will call this directory ../your-jmol-directory.

Every web page within your site should refer to ../your-jmol-directory using a relative url. Directory relative paths which start with . or .. should always be used. Server relative paths which start with / might be acceptable in special circumstances. Absolute URLs which start with http:// are evil and should never be used.
Every page must contain the following HTML command in the head section in order to include the Jmol.js library:
  <head>
    ...
    <script src="../your-jmol-directory/Jmol.js"></script>
    ...
  </head>
Every page must contain a call to jmolInitialize(codebaseDirectory) as the first call into the Jmol.js library.
Every page that contains buttons/checkboxes/radio buttons/menu controls must contain bracketing <form>/</form> tags. It is generally safe to open this tag immediately after the body tag and close it immediately before the /body tag.
  <body>
    <form>
    ...
    </form>
  </body>
</html>

Basic Scripting Commands

jmolInitialize

jmolInitialize(codebaseDirectory) Initializes the Jmol.js JavaScript library. The call to jmolInitialize() must be within the <body> of the HTML page. The required codebaseDirectory parameter specifies the relative path of the directory containing the Jmol applet files.

jmolApplet

jmolApplet(size, {script}, {nameSuffix}) Allocates an JmolApplet. size should generally be an integer pixel count in the range 100 to 800. script is a script that will be run after the molecular model is loaded.
Advanced: nameSuffix should 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.

Advanced: JmolApplet instances should generally be square. If your application requires a rectangular JmolApplet, then the size parameter may be specified as an array containing two elements ... width and height specified in pixel counts. This is usually easiest to specify using JavaScript square bracket notation for array constants ... as in [400, 200]. The size must be fixed; percentages are not allowed. Otherwise, many browsers die when the browser window is resized.

jmolButton

jmolButton(script, {label}, {id})
Draws a button with a text label. If label is not specified it defaults to the first 32 chars of the script. script is run when the button is pressed.

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

jmolCheckbox

jmolCheckbox(scriptWhenChecked, scriptWhenUnchecked, labelHtml, {isChecked}, {id})
Displays a checkbox. scriptWhenChecked is run when the checkbox is checked by the user. scriptWhenUnchecked is run when the user unchecks the checkbox. labelHtml is placed immediately after the checkbox. isChecked should be set to a non-false value if you want the default state.

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

jmolRadioGroup

jmolRadioGroup(arrayOfRadioButtons, {separatorHtml}, {groupName})
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.

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

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

jmolLink

jmolLink(script, text, {id})
text is written as a link. script is run when the user clicks on the link.

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

jmolMenu

jmolMenu(arrayOfMenuItems, {menuHeight}, {id})
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.

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 of the menuHeight parameter is -1 then the menu height will automatically be calculated to be the same length as the number of items, thereby eliminating any scrolling.

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

Intermediate Scripting Commands

jmolSetAppletColor

jmolSetColor(bgcolor, {boxfgcolor}, {progresscolor}, {boxbgcolor}) Used to set the background color of the applet. bgcolor is specified using HTML "#RRGGBB" notation or as one of the 140 JavaScript color names .
Advanced: The text color and progress bar color for the Java Plug-in can optionally be set.

jmolHtml

jmolHtml(html)
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>html<script>

jmolBr

jmolBr()
The same as jmolHtml(" ") which is the same as </script><br /><script>

jmolAppletInline

jmolAppletInline(size, inlineModel, {script}, {nameSuffix})
Creates an instance of the JmolApplet, but passes in the contents of the molecular model rather than a file name or URL. If you are not pulling your molecular model data from a database then you probably do not want to use this.

jmolLoadInline

jmolLoadInline(model, {targetSuffix})
Used in database applications where the molecular model is available as a string. This directly loads model into the applet. Note that this is not the file name ... it is the contents of the file.

jmolScript

jmolScript(script, {targetSuffix})
Use this if you want to construct your own UI controls or to execute script based upon JavaScript events. The UI controls above are essentially implemented using this jmolScript function. When more than one JmolApplet is being displayed, targetSuffix is used to identify a particular instance.

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.

jmolSetTarget

jmolSetTarget(targetSuffix)
Do not use this unless you are displaying multiple applets at the same time and your Jmol.js UI controls are not sequentially following their associated jmolApplet invocations.

If you understood the previous sentence then you can probably figure out what jmolSetTarget does.

All JmolApplets which are generated by the Jmol.js library start with the name/id jmolApplet. By default they are numbered sequentially starting from 0. So, both the name and id of the first and second applets on the page default to jmolApplet0 and jmolApplet1. You are encouraged to provide your own suffixes in your calls to jmolApplet and use those suffixes in jmolSetTarget.

jmolRadio

jmolRadio(script, {labelHtml}, {isChecked}, {separatorHtml})
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. Radio buttons will be assigned to the same group until you call jmolStartNewRadioGroup.

jmolStartNewRadioGroup

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

jmolCheckBrowser

jmolCheckBrowser(action, urlOrMessage, nowOrOnClick)
Checks users web browser for compliance and compatibility with Jmol.

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". 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. nowOrOnClick defaults to "onClick";

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

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.

Hosted by