jQuery-Jmol - a jQuery plugin for Jmol

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