Difference between revisions of "Jmol JavaScript Object/JME"

From Jmol
Jump to navigation Jump to search
(update of descriptions (mostly, Java left behind))
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Integration of JSME into JSmol =
+
== Integration of JSME into JSmol ==
JSME, the JavaScript Molecular Editor by Peter Ertl, evolved from the former [http://www.molinspiration.com/jme/ JME applet].  
+
'''JSME, the JavaScript Molecule Editor''' by Peter Ertl and Bruno Bienfait <sup>[1]</sup>, evolved from the former JME applet <sup>[2]</sup>.  
It allows the user to draw a molecular structure in 2D. The '''JSmol object library''' includes the capability to pass information back and forth between JSME and JSmol in a seamless manner. The "information panel" that JSmol library implements can be set up to also hold the JSME object, allowing tight integration. Alternatively, JSME and JSmol objects can be set side-by-side on a web page, and communication between both objects can be handled by the page developer.  
+
It provides tools for the user to draw a molecular structure in 2D. The '''JSmol object library''' includes the capability to pass information back and forth between JSME and JSmol in a seamless manner. The "information panel" that JSmol library implements can be set up to also hold the JSME object, allowing tight integration. Alternatively, JSME and JSmol objects can be set side-by-side on a web page, and communication between both objects can be handled by the page developer.  
  
 
== Creating and inserting JSME ==  
 
== Creating and inserting JSME ==  
To create a JSME object, use for example:
 
var myJME = Jmol.getJMEApplet("myJME", Info, myJmol);
 
 
''(Note that although the syntax is reminiscent of the former Java applets, no Java is currently involved here)''  
 
''(Note that although the syntax is reminiscent of the former Java applets, no Java is currently involved here)''  
  
The 3rd argument, if provided, is a pointer to a JSmol object that will contain this JSME drawing panel as a 2D input option inside its Info panel.
+
The name of the unique '''<code>Jmol</code>''' object is literal, cannot be changed.
 +
On the contrary, the <code>myJME</code>, <code>myJmol</code>, <code>JmeInfo</code>, <code>JmolInfo</code> names used in these examples are user-declared variables and may be different.
  
Parameters making the <code>Info</code> variable (with default values shown):
+
There are two ways of inserting JSME using the JSmol library: independent and embedded; you can see a demonstration of both at [http://jmol.org/demo/ the main Jmol website].
* '''height''' <code>300</code>
+
 
* '''width''' <code>300</code>
+
=== Independent JSME ===
* '''j2sPath''' <code>"j2s"</code>
+
The JSME panel takes a space of its own in the page.
* '''options''' <code>"autoez"</code>
+
 
** rbutton, norbutton - show / hide R button
+
In preparation, your web page must call 2 files (this is usually done in the <code>head</code> section):
** hydrogens, nohydrogens - display / hide hydrogens
+
* {{file|JSmol.min.js}}
** query, noquery - enable / disable query features
+
* {{file|jsme.nocache.js}}. This may be:
** autoez, noautoez - automatic generation of SMILES with E,Z stereochemistry
+
** A copy of the JSME package included in JSmol distribution, in the {{folder|jsme}} folder.
** nocanonize - SMILES canonicalization and detection of aromaticity supressed
+
** The {{folder|jsme}} folder in the distribution file of the JSME package  (e.g. to use a specific version)
** nostereo - stereochemistry not considered when creating SMILES
+
 
** reaction, noreaction - enable / disable reaction input
+
To create and insert the JSME object, use:
** multipart - possibility to enter multipart structures
+
Jmol.getJMEApplet("myJME", JmeInfo);
** number - possibility to number (mark) atoms
+
Where the <code>JmeInfo</code> variable must include at least:
** depict - the applet will appear without editing butons,this is used for structure display only
+
* '''height''': <code>350</code>
** Documented at [http://www2.chemie.uni-erlangen.de/services/fragment/editor/jme_functions.html]
+
* '''width''': <code>300</code>
 +
And the JSME panel will be inserted at the point of execution of this JavaScript code.
 +
If you need to include this code elsewhere, you can specify a target div where the JSME panel will be inserted, by adding this parameter:
 +
* '''divid''': "''my_target_div''"
 +
 
 +
=== JSME embedded in JSmol ===
 +
In this mode, the JSME panel shares the space in the page with a JSmol panel; only one is displayed at a time and their contents (2D vs. 3D) are automatically interconverted to match.
 +
 
 +
In preparation, your web page must call 3 files (this is usually done in the <code>head</code> section):
 +
* {{file|JSmol.min.js}}
 +
* {{file|JSmolJME.js}} in the {{folder|js}} folder of the JSmol package
 +
* {{file|jsme.nocache.js}} included in JSmol distribution, in the {{folder|jsme}} folder.
 +
** Note: you could replace the whole {{folder|jsme}} subfolder with the one included in the distribution file of the JSME package  (e.g. to use a specific version)
 +
 
 +
To create and insert the JSmol and JSME objects, use:
 +
Jmol.getApplet("myJmol", JmolInfo);
 +
Jmol.getJMEApplet("myJME", JmeInfo, myJmol);
 +
The 3rd argument is a pointer to the associated JSmol object, that will contain this JSME panel as a 2D input option inside its Info panel.
 +
User interface controls (like buttons or links) may be implemented in the page for switching between
 +
2D (JSME) and 3D (JSmol) displays.
 +
 
 +
In this case, the <code>JmeInfo</code> variable must include at least:
 +
* '''height''': <code>350</code>
 +
* '''width''': <code>300</code>
 +
* '''visible''': <code>true</code>  for the JSME panel to be displayed initially (JSmol panel hidden)
 +
 
 +
=== JSME options ===
 +
Other parameters that may be included in the <code>JmeInfo</code> variable are:
 +
* '''options''': "''comma-delimited list''"
 +
** <code>depict</code> - the canvas will appear without editing buttons, i.e. used for structure display only
 +
** <code>zoom</code> - allow zooming of the molecular drawing
 +
** <code>rButton</code> - display the R button
 +
** <code>hydrogens</code> - display hydrogens
 +
** <code>query</code> - allow query features
 +
** <code>autoEZ</code> - automatic generation of SMILES with E,Z stereochemistry
 +
** <code>canonize</code> - SMILES canonicalization and detection of aromaticity
 +
** <code>stereo</code> - stereochemistry not considered when creating SMILES
 +
** <code>useOpenChemLib</code> - use the [https://github.com/Actelion/openchemlib OpenChemLib library] for SMILES conversion, 2D coordinates computation and SVG export
 +
** <code>exportSVG</code> - enable the menu item for SVG export
 +
** ...and [[Jmol JavaScript Object/JME/Options|more]], all documented at [https://peter-ertl.com/jsme/ Peter Ertl's site]
 +
Most options are negated by prepending with "no", e.g. <code>nozoom</code>; a few have specific keywords for the opposite choice. The options are case-insensitive.
  
 
== JSME-specific methods ==
 
== JSME-specific methods ==
All these functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed):
+
All the following functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed).
  Jmol.jmeGetFile(myJME, asJME)  
+
The <code>myJME</code> name used in these examples is, in contrast, a user-declared variable and may be different.
  Jmol.jmeOptions(myJME, options)
+
 
  Jmol.jmeReadMolecule(myJME, jmeOrMolData)
+
For retrieving data from JSME:
  Jmol.jmeReset(myJME)  
+
  Jmol.jmeGetFile(myJME, true) // molecular data in the JME format
  Jmol.jmeSmiles(myJME, withStereoChemistry)
+
Jmol.jmeGetFile(myJME, false) // molecular data in the MOL format
 +
  Jmol.jmeSmiles(myJME, ''withStereoChemistry'') // molecular data in the SMILES format (with or without stereo information)
 +
 
 +
For loading structures into JSME:
 +
  Jmol.jmeReadMolecule(myJME, ''jmeOrMolData'')
 +
sends data as a string that will be interpreted either in JME or MOL formats, depending on the presence of newline characters in that string.
 +
 
 +
''Note:'' Feeding SMILES data into JSME is possible, but a dedicated method is not currently implemented in the JSmol library.
 +
You can achieve it using a call to an internal function:
 +
myJME._applet.readGenericMolecularInput( ''smilesData'' );
 +
 
 +
For other tasks:
 +
  Jmol.jmeOptions(myJME, ''options'') // to set options after the object has been created
 +
  Jmol.jmeReset(myJME)
 +
 
 +
== References ==
 +
# [https://jsme-editor.github.io/ JSME Molecule Editor]
 +
# [https://web.archive.org/web/20200531080042/https://www.molinspiration.com/jme/ JME applet] (archived copy; the page dos not exist any more)

Latest revision as of 06:47, 31 May 2024

Integration of JSME into JSmol

JSME, the JavaScript Molecule Editor by Peter Ertl and Bruno Bienfait [1], evolved from the former JME applet [2]. It provides tools for the user to draw a molecular structure in 2D. The JSmol object library includes the capability to pass information back and forth between JSME and JSmol in a seamless manner. The "information panel" that JSmol library implements can be set up to also hold the JSME object, allowing tight integration. Alternatively, JSME and JSmol objects can be set side-by-side on a web page, and communication between both objects can be handled by the page developer.

Creating and inserting JSME

(Note that although the syntax is reminiscent of the former Java applets, no Java is currently involved here)

The name of the unique Jmol object is literal, cannot be changed. On the contrary, the myJME, myJmol, JmeInfo, JmolInfo names used in these examples are user-declared variables and may be different.

There are two ways of inserting JSME using the JSmol library: independent and embedded; you can see a demonstration of both at the main Jmol website.

Independent JSME

The JSME panel takes a space of its own in the page.

In preparation, your web page must call 2 files (this is usually done in the head section):

  • File icon.gifJSmol.min.js
  • File icon.gifjsme.nocache.js. This may be:
    • A copy of the JSME package included in JSmol distribution, in the Folder icon.gifjsme folder.
    • The Folder icon.gifjsme folder in the distribution file of the JSME package (e.g. to use a specific version)

To create and insert the JSME object, use:

Jmol.getJMEApplet("myJME", JmeInfo);

Where the JmeInfo variable must include at least:

  • height: 350
  • width: 300

And the JSME panel will be inserted at the point of execution of this JavaScript code. If you need to include this code elsewhere, you can specify a target div where the JSME panel will be inserted, by adding this parameter:

  • divid: "my_target_div"

JSME embedded in JSmol

In this mode, the JSME panel shares the space in the page with a JSmol panel; only one is displayed at a time and their contents (2D vs. 3D) are automatically interconverted to match.

In preparation, your web page must call 3 files (this is usually done in the head section):

  • File icon.gifJSmol.min.js
  • File icon.gifJSmolJME.js in the Folder icon.gifjs folder of the JSmol package
  • File icon.gifjsme.nocache.js included in JSmol distribution, in the Folder icon.gifjsme folder.
    • Note: you could replace the whole Folder icon.gifjsme subfolder with the one included in the distribution file of the JSME package (e.g. to use a specific version)

To create and insert the JSmol and JSME objects, use:

Jmol.getApplet("myJmol", JmolInfo);
Jmol.getJMEApplet("myJME", JmeInfo, myJmol);

The 3rd argument is a pointer to the associated JSmol object, that will contain this JSME panel as a 2D input option inside its Info panel. User interface controls (like buttons or links) may be implemented in the page for switching between 2D (JSME) and 3D (JSmol) displays.

In this case, the JmeInfo variable must include at least:

  • height: 350
  • width: 300
  • visible: true for the JSME panel to be displayed initially (JSmol panel hidden)

JSME options

Other parameters that may be included in the JmeInfo variable are:

  • options: "comma-delimited list"
    • depict - the canvas will appear without editing buttons, i.e. used for structure display only
    • zoom - allow zooming of the molecular drawing
    • rButton - display the R button
    • hydrogens - display hydrogens
    • query - allow query features
    • autoEZ - automatic generation of SMILES with E,Z stereochemistry
    • canonize - SMILES canonicalization and detection of aromaticity
    • stereo - stereochemistry not considered when creating SMILES
    • useOpenChemLib - use the OpenChemLib library for SMILES conversion, 2D coordinates computation and SVG export
    • exportSVG - enable the menu item for SVG export
    • ...and more, all documented at Peter Ertl's site

Most options are negated by prepending with "no", e.g. nozoom; a few have specific keywords for the opposite choice. The options are case-insensitive.

JSME-specific methods

All the following functions must be applied to the unique Jmol object (this name is literal, cannot be changed). The myJME name used in these examples is, in contrast, a user-declared variable and may be different.

For retrieving data from JSME:

Jmol.jmeGetFile(myJME, true) // molecular data in the JME format
Jmol.jmeGetFile(myJME, false) // molecular data in the MOL format
Jmol.jmeSmiles(myJME, withStereoChemistry) // molecular data in the SMILES format (with or without stereo information)

For loading structures into JSME:

Jmol.jmeReadMolecule(myJME, jmeOrMolData) 

sends data as a string that will be interpreted either in JME or MOL formats, depending on the presence of newline characters in that string.

Note: Feeding SMILES data into JSME is possible, but a dedicated method is not currently implemented in the JSmol library. You can achieve it using a call to an internal function:

myJME._applet.readGenericMolecularInput( smilesData );

For other tasks:

Jmol.jmeOptions(myJME, options) // to set options after the object has been created
Jmol.jmeReset(myJME)

References

  1. JSME Molecule Editor
  2. JME applet (archived copy; the page dos not exist any more)

Contributors

AngelHerraez