Download

The project itself is hosted on GitHub. You can view it here.

Current version is: 2.0

Installation

<!DOCTYPE html> 
<html lang="en">
<head> 
  <meta charset="utf-8">
  <title>jMol Site</title>
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js"></script>
  <script type="text/javascript" src="jquery.jmol.min.js"></script>
  <script type="text/javascript" src="main.js"></script>
</head>
<body>
  <div id="my-jmol-viewer">This content will be replaced with Jmol applet</div>
</body>
</html>

Initialization

The contents of main.js:

$(document).ready(function(){
  $('#my-jmol-viewer').jmol({
    appletUrl : '/jmol/',
    width: 640,
    height: 480,
    menuUrl : '/jmol/jmol.mnu',
    modelUrl : '/test.pdb',
    background: '#FFFFFF',
  });
});

Documentation

Options

appletUrl
URL to the directory where Jmol applets reside (default: empty)
background
background color of Jmol applet (default: '#000000')
height
height of an applet window (default: 300)
memLimit
Java memory limit in megabytes (default: 512)
menuUrl
Jmol menu file URL (default: 'jmol.mnu')
modelUrl
model file to load at startup (default: empty)
width
Width of an applet window (default: 400)
useSigned
Weather to load a signed or unsigned applet (default: false)

There are also callback options, where you specify your own callback function.

onEval(jmol, args)

get's called when javascript code has to be evaluated from Jmol applet. Arguments:

  • jmol - a JmolWrapper object
  • args - an array of arguments sent by Jmol applet

Eval callback must be defined at initialization (it can not be changed).

onDestroy(void)

get's called right after destruction of Jmol applet.

onReady(jmol)

get's called when Jmol applet is ready. Arguments:

  • jmol - a JmolWrapper object
onSync(jmol)

get's 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. Arguments:

  • jmol - a JmolWrapper object

Events

All the other Jmol applet callback are translated into.

jmol_animate

invoked when Jmol applet does animation. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • frameIdx - current frame index number (starting with 0)
  • fileNum - current file number (starting with 1)
  • modelNum - current model number within the current file (starting with 1)
  • firstFrame - first frame of the animation range, expressed as fileNo x 1000000 + modelNo
  • lastFrame - last frame of the animation range, expressed as fileNo x 1000000 + modelNo
  • animState - 0 (animation is off) or 1 (animation is on)
  • animDir - current animation direction, either 1 or -1
  • direction - current direction, either 1 (forward) or -1 (reverse)
jmol_echo

invoked when Jmol applet sends an echo message. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • msg - a string message
jmol_hover

invoked when a mouse hovers an atom. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • label - a string that depends upon the setting of the hover label for the hovered atom (see scripting documentation)
  • atomIdx - atom index, starting with 0
jmol_load

invoked when a model file has been loaded. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • fileUrl - the URL of the loaded file (full path+filename)
  • fileName - the filename of the loaded file (without the path)
  • title - the internal title of the model in the loaded file
  • errorMsg - any error messages generated
  • status - a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed
  • frameBefore - 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)
  • frameLast - a text string with the last frame number after loading the current model, in file.model syntax
jmol_measure

invoked when a measurement has been made. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • label - a string that depends upon the setting of the measurement label (see scripting documentation)
  • status - status message of measurement task (started, ended, picked)
  • value - floating point value of measurement
jmol_message

invoked when Jmol applet sends a status message. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • msg - a string message
jmol_minimize

invoked when Jmol applet does minimization. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • status - text indicating the current status of a currently running minimization: either starting, running, or done
  • iteration - the number of the iteration
  • energy - a number with the value of energy (E) at that step
  • energyDelta - a number with the decrease in energy (dE) at that step
jmol_pick

invoked when a mouse picks (selects, clicks) an atom. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • label - a string that depends upon the setting of the pick label for the selected atom (see scripting documentation)
  • atomIdx - atom index, starting with 0
jmol_resize

invoked when a Jmol applet's size changes. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • data - a data object

data object contents:

  • width - width in px
  • height - height in px
jmol_script

invoked when Jmol applet sends a script message. Handler arguments:

  • event - jQuery event object
  • jmol - a JmolWrapper object
  • msg - a string message

Methods

You can call a method on initialized jQuery-Jmol plugin with $(...).jmol(command);

destroy

Destroy jQuery-Jmol and Jmol applet and remove it from DOM.

hide

Hide Jmol applet. Never use display:none or .hide() method!

option

Update a sigle option or a set of options in jQuery-Jmol.

To update a single option:

$(...).jmol('option', name, value);

To update multiple options:

$(...).jmol('option', { ... key - value pairs ... });
show

Show Jmol applet.

JmolWrapper

JmolWrapper is an internal reference object, that acts as:

  • a script cache while applet has not yet been initialized;
  • a callback reference counter, to set up callbacks when a event binding has been requested;
  • a wrapper for Jmol applet's interface exporting only neccessary methods.

JmolWrapper is always sent as second parameter in jmol_* events and as a first parameter to callbacks. Also it's stored in .data('jmol') of the block that was used to initialize jQuery-Jmol. For example:

$('#my-jmol').jmol({
	.. init options ..,
	onReady = function(jmol){
	  // here you have a reference to JmolWrapper in jmol variable
	  var prop = jmol.getProperty(... params ...);
	};
});
// Later on ...
var my_jmol = $('#my-jmol').data('jmol');
my_jmol.script(... script source ...);
							

List of public properties:

id

The ID of applet's HTML element.

List of public methods:

getProperty(property, value)

Get a property from Jmol.

Arguments:

  • property - a string name
  • value - a string name (optional)

Returns: object

script(source)

Send a script to Jmol.

Arguments:

  • source - a string script source

Returns: void

scriptWait(source)

Send a script to Jmol (bypases the queue and returns callback information)

Arguments:

  • source - a string script source

Returns: string

scriptWaitOutput(source)

Send a script to Jmol (bypases the queue and wait for any output from messages, echo, print, etc.)

Arguments:

  • source - a string script source

Returns: string

scriptNoWait(source)

Send a script to Jmol (put it on the queue)

Arguments:

  • source - a string script source

Returns: string

scriptCheck(source)

Validate script's syntax and return errors, if any.

Arguments:

  • source - a string script source

Returns: string

Examples

Roadmap

  • Testing and debugging;
  • Build a CSS framework and a default theme so to replace the need for an old jmolButton, jmolCheckbox methods;
  • Create additional helper library to parse measurement messages and add atom information to measurement object as well. Also parse hover, pick and other string messages to form an object representation.

Changelog

2012.08.10 2.0.0

Complete rewrite. Introduced a Jmol applet wrapper object. Overriden .bind() and .unbind() methods in jQuery to set up callbacks when neccessary.

2012.08.05 1.3.0

Separate jQuery call .jmolscript() for Jmol scripting. .jmol() now takes 3 different string options for initialized plugin: hide (hide applet), show (show applet), destroy (destroy applet and plugin instance)

2012.07.18 1.2.0 (not released)

Removed data mangling from measurement, hovering and picking callbacks - raw string data will be passed to user. Introduced Jmol.js (version 3.0) scripting library to aid development.

2012.07.12 1.1.0

Only messaging callbacks are available as callback options through jQuery. Hover, pick, load, ready and destroy are now sent as an event, so you can bind and unbind a listener. Also the plugin does not replace the placeholder, but instead use it as a base object, applet gets appended inside with an ID of placeholder preceding with underscore.

2012.07.11 1.0.2 alpha

Timeout did not work, so I found that ready callback sent an extra parameter - internal Java object with all the public methods.

2012.07.11 1.0.1 alpha

Removed applet file name from jQuery options, now they are hard coded Introduced useSigned:Boolean option, weather to load signed or unsigned applet Little more cheating on unresponsive Java applet - reset DOM tree and try to push scripts after setTimeout

2012.07.10 1.0.0 alpha

Initial release