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
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 "jmol-" . By default they are numbered
sequentially starting from 0. If you have the need/desire to provide
your own suffix then do so with your calls to jmolApplet .
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 .
|