Installation of the JSME molecule editor

Introduction

This document describes how to embed JSME into a web page.
The first section describes how to migrate pages that use the JME Java applet.
The second part shows how to install JSME using JavaScript.

Migration from JME to JSME

The HTML pages that use the "applet" tag can easily adapted thanks to the provided JavaScript code. Pages that use other methods to embed a Java applet, using the "object" or the "embed" tags are presently not supported.

HTML modification for pages using the "applet" tags

Many websites still use the JME Java applet. Migrating an HTML page from JME to JSME is basically a two steps process:
Example of simple html page with a Java JME applet:
<html>
<head>
<title>JME Example</title>
</head>

<body>
<applet code="JME.class" name="JME" archive="JME.jar" width="360" height="315" id="JME">
You have to enable Java and JavaScript in your browser to use JME!
</applet>
</body>
</html>

The same page after migration to JSME:
<html>
<head>
<script type="text/javascript" language="javascript" src="jsme/jsme.nocache.js"></script>
<title>JME Example</title>
</head>

<body>
<div code="JME.class" name="JME" archive="JME.jar" width="360" height="315" id="JME">
You have to enable JavaScript in your browser to use JSME! </div>
</body>
</html>


This example page can be tested in your browser: JME_to_JSME_simple.html

Important warning

Due to an Internet Explorer bug, the id of any DIV element may never be "JSME".

Here is an example for which some older versions of Internet Explorer will fail:
<div id="JSME" "code="JME.class" name="JME" archive="JME.jar" width="360" height="315" id="JME">
You have to enable JavaScript on your machine ! </div>

Accessing the applet variable in the JavaScript code

Java applets can be accessed in the JavaScript code in three different ways:

With JSME, the equivalent JavaScript applet can be accessed in the JavaScript code in two different ways:

The third method is not supported.

If your HTML page uses the document.applets to access the JME applets, then all occurences of document.applets will need to be replaced by document.jsapplets.


Example:
<div code="JME.class" name="JME1" archive="JME.jar" width="360" height="315" id="JME">
You have to enable JavaScript on your machine ! </div>
<div code="JME.class" name="JME2" archive="JME.jar" width="360" height="315" id="JME">
You have to enable JavaScript on your machine ! </div>>

The code to access them using the variable name and the jsapplets array is shown below:
<input type="button" value="Get smiles via document.JME1" onclick="alert(document.JME1.smiles());">
<input type="button" value="Get smiles via document.jsapplets[1]" onclick="alert(document.jsapplets[1].smiles());">

Timing issue with the initialization of the JavaScript applet using body.onload()

Java applets can be initialized using some JavaScript code after the page has finished loading. Unfortunately, the "body.onload()" method that is usually used for this purpose cannot be used with JSME because some JSME instances might not be ready when the body.onload method is called.
To solve this problem, the JSME initialization can call a function named "jsmeOnLoad" that contains custom initialization code.

Example of simple html code with a "body.onload()" for the Java applet JME:
<body onLoad="loadJmeFile();loadMolFile();">

Example of simple html code with an empty "body.onload()" and a "jsmeOnLoad" function for JSME:
<script>
function jsmeOnLoad() {
    loadJmeFile();loadMolFile();
}
</script>

<body onLoad="">

Example of JME to JSME pages

Implementation note

After being loaded, the JSME JavaScript code scans the HTML page looking for all DIV elements have a code attribute as code="JME.class". The JavaScript code that performs this task is available as a function named replaceAllAppletsByJSME(). For more information about this function, see the API section.

Installation of JSME using JavaScript code

To install JSME in a web page requires three items:
<html>

<head>
<script type="text/javascript" language="javascript" src="jsme/jsme.nocache.js"></script>
<script>
 //this function will be called after the JavaScriptApplet code has been loaded.
    function jsmeOnLoad() {
        jsmeApplet = new JSApplet.JSME("jsme_container", "380px", "340px");
   }
</script>
 </head>
<body>
<div id="jsme_container"></div>

</body>
</html>
The HTML code above can be tested here.

The use of a the "jsmeOnLoad" function is necessary only if a JSME instance needs to be available immediately after the HTML page has been loaded. For more information, see the timing issue defined above.

The example code above is minimalist, it is actually not very useful because it does not show how to use the JavaScript variable "jsmeApplet" that was created.
Here is a new example with a button that displays the SMILES of the molecule drawn in the editor:
<html>

<head>
<script type="text/javascript" language="javascript" src="jsme/jsme.nocache.js"></script>

<script>
 //this function will be called after the JavaScriptApplet code has been loaded.
    function jsmeOnLoad() {
        jsmeApplet = new JSApplet.JSME("jsme_container", "380px", "340px");
   }
</script>
</head>
<body>
<div id="jsme_container"></div>

<button type="button" onclick="alert(jsmeApplet.smiles())">Show SMILES</button>
</body>
</html>
The HTML code above can be tested here.

The function used to created a new JSME instance can accept a third argument. The purpose of this optional argument is to provide customization of JSME:

<html>

<head>
<script type="text/javascript" language="javascript" src="jsme/jsme.nocache.js"></script>

<script>
 //this function will be called after the JavaScriptApplet code has been loaded.
    function jsmeOnLoad() {
        jsmeApplet = new JSApplet.JSME("jsme_container", "380px", "340px", {
            "options" : "oldlook,marker"
            });
</script>
</head>
<body>
<div id="jsme_container"></div>

<button type="button" onclick="alert(jsmeApplet.smiles())">Show SMILES</button>
</body>
</html>

The HTML code above can be tested here.

JSME API

The API of JSME includes the API of the java applet JME plus new functions and methods. A summary of the API is presently available as a JavaDoc file.

JSME parameters

The JSME instance can be customized using a set of parameters. These parameters must be provided as a third argument JavaScript object or as a "param" construct.

Several parameters are available to initialize JSME.

All the parameter values must be input as character string. options - list of comma separate keywords (See JSME option section).
jme - structure in JME format
smiles - structure in SMILES format
mol - structure in MOL format
depictcgi - ??
depictbg - background color in depict mode in RGB hex format (e.g. #FFFFFF)
guicolor - background color of the GUI elements in RGB hex format (e.g. #FFFFFF) (see also method setUserInterfaceBackgroundColor() )
guiAtomColor - set atom symbol color in the GUI to the same color in RGB hex format (e.g. #000000 for black) atombg - atom background colors - see the demo JSME_atom_highlight_demo.html for an example
depictbg - background color for the depict mode in hex format - no test yet
atombgsize - relative size of the atom background circle, default is "1.0"
bondbgsize - relative size of the bond background rectangle, default is "1.0"
markerIconColor - background color of the GUI element circle use for the marker action in RGB hex format(e.g. #FFFFFF)
notify_structural_change_js_function - deprecated

JSME options

Several options are available to customize the look and behavior of JSME.

Recognized keywords are :

xbutton, noxbutton - show / hide the X button (default is xbutton)
rbutton, norbutton - show / hide the R button (to mark connection of substituent with the main scaffold)
atommovebutton, noatommovebutton - show / hide the atom move button (default is noatommovebutton)
hydrogens, nohydrogens - display / hide implicit hydrogens on heteroatom labels (default is hydrogens). Implicit hydrogens are calculated only if the valence state option is switched on
keephs, removehs - remove hydrogens when reading a molecule with explicit hydrogens (default is keephs). This option can be used to remove hydrogens when pasting a structure with explicit hydrogens comning from e.g. the Pubchem database
keephs, removehsc - remove hydrogens bounded to C when reading a molecule with explicit hydrogens (default is keephs). This option can be used to remove hydrogens when pasting a structure with explicit hydrogens comning from e.g. the Pubchem database
query, noquery - enable / disable query features (default is noquery). In query mode, a SMARTS is generated when a smiles is requested.
autoez, noautoez - automatic generation of SMILES with E,Z stereochemistry (default is autoez). Option "stereo" must enabled.
canonize,nocanonize - SMILES canonicalization and detection of aromaticity supressed (default is canonize)
stereo,nostereo - stereochemistry not considered when creating SMILES (default is stereo)
reaction, noreaction - enable / disable reaction input
multipart, nomultipart - possibility to enter multipart structures (default multipart)
addnewpart, noaddnewpart - when reading or pasting a new molecule, add it to the existing molecules or replace them (used only if option multipart is set)
valenceState, noValenceState - compute charge and hydrogen count
polarnitro, nopolarnitro - prevent automatic conversion of nitro (and similar) groups into nonpolar form (default is nopolarnitro)
number / autonumber - possibility to number (mark) atoms
marker, nomarker - possibility to highlight atoms (default is nomarker). All highlighted atoms will have an atom map number equal to 1. The atom map numbers are included in the exported SMILES and MOL.
marker1, nomarker1 - possibility to highlight one atom at a time (default is nomarker1). The highlighted atom will have an atom map number equal to 1. The atom map number is included in the exported SMILES and MOL.
markAtomOnly, noMarkAtomOnly - mark atom only.
markBondOnly, noMarkBondOnly - mark bond only.
markNothing, noMarkNothing - disable marking action, existing highlighted atoms or bonds are still shown.
pseudoMark, nopseudoMark - no atom marking happens but an atom mark event is triggered.
showAtomMapNumberWithBackgroundColor, noshowAtomMapNumberWithBackgroundColor -display background color for atoms with a valid atom map. The atom map number is used as an index in the background color palette (starting at 1) depict, nodepict - the applet will appear without editing buttons, this is used for structure display only (default nodepict)
depictaction, nodepictaction - allow structure editing in depict mode
toggle, notoggle - allow to switch automatically between editing and depict mode (default is notoggle)
fullScreenIcon, nofullScreenIcon - show or hide the fullscreen icon (Note: this feature is still buggy)
showFullScreenIconInDepictMode, noshowFullScreenIconInDepictMode - show or hide the fullscreen icon in depict mode
paste, nopaste - enabling and disabling the paste action including drop of a MOL/RXN on the applet., can be used together with the depict option to have a read only depiction. Pasting is disabled by default in depict modet
border, noborder (used together with the depict option) - displays a border around depicted molecule (default is noborder)
newlook, oldlook - turn on/off the old Java based JME look (default is newlook)
exportinchi, noexportinchi - enable / disable the menu item forInChI export (http://www.inchi-trust.org/)
exportinchikey, noexportinchikey - enable / disable the menu item for InChI key export (http://www.inchi-trust.org/)
exportinchiauxinfo, noexportinchiauxinfo - enable / disable the menu item for InChI auxinfo export (http://www.inchi-trust.org/)
searchinchiKey, nosearchinchiKey - enable / disable the menu item to search InChI key on the web (http://www.inchi-trust.org/)
useopenchemlib, nouseopenchemlib - use the OpenChemLib library (https://github.com/Actelion/openchemlib) for SMILES conversion, 2D coordinates computation and SVG export
exportSVG, noexportSVG - enable / disable the menu item for SVG export (useopenchemlib must be set))
useOclidcode, nouseOclidcode - enable / disable the menu item for OCL export (useopenchemlib must be set))
fgmenu, nofgmenu - enable / disable the top menu item for functional groups
zoom, nozoom - turn on/off zooming of the molecular drawing area and the GUI, on by default
zoomgui, nozoomgui - turn on/off zooming of the GUI. zoom option must be on, can be used to disable zooming on the gui part
showdragandDropIconindepictmode, noShowdragandDropIconindepictmode show or hide the drag and drop icon (blue triangle) in depict mode
contextmenu, nocontextmenu - enable / disable the context menu

The option of a JMSE instance can be setup during its creation or afterwards using the options() method. See the JSME API section.

JSME Callbacks

Introduction

JSME provides a callback mechanism where JavaScript functions are called before or after a specific event has happened in JSME. One of the most useful callback is the "AfterStructureModified" that allows the creation of interactive HTML pages that track any structure change, for instance to compute and display of a 3D structure. The JavaScript functions are defined in the HTML page and set using the "setCallBack()" method. This method needs two arguments, a callback name and a JavaScript function.

Example


function showSmiles(jsmeEvent) {
	var jsme = jsmeEvent.src;
	var smiles = jsme.smiles();
	alert(smiles);
}

jsmeApplet.setCallBack("AfterStructureModified", showSmiles);

The JSME event variable

Each callback function received one argument: a JSMEevent object. This object contains several fields that may or may be not defined according the event type. The fields of JSMEevent are:

Predefined callback names

BeforePaste

AfterPaste

AfterStructureModified

AtomHighlight

BondHighlight

AtomClicked

BondClicked

InchiKeySearch

The JSME callback system is work in progress.

The InchiResult variable

InchiResult objects are generated by the Javascript InChI computation implemented in JSME. The fields of InchiResult are: