MediaWiki

Running Jmol / JSmol

• Jmol as a standalone application.
• J(S)mol as a web applet or HTML5 object.
  • compatibility with JavaScript frameworks or libraries.
• J(S)mol embedded in wikis or blogs.
• Borrowed JSmol, or running JSmol without your own server.
• Running Jmol using Java Web Start.
• JSmol in a Jupyter notebook.
• Jmol in an Android tablet.
• Troubleshooting.

Description

MediaWiki is an open source wiki engine licensed under the GNU General Public License. It is used by many websites, including this one.

The Jmol Mediawiki Extension enables the use of the Jmol applet inside of Mediawiki pages. This basic page and this simple page demonstrate how to use the extension.

Current version: 3.3_dev (You can check which version a Wiki is using by going to the Special:Version page in that Wiki.

Current status: the Jmol Mediawiki Extension is fully functional and stabilized. It currently needs to be modified for a few things: better security, ability to delay loading the applet.

Security is hopefully correct now. The delay effect can be obtained by using Jmol applet in a popup window.

Wikis using the Jmol Extension

If you know a Wiki using the Jmol MediaWiki Extension, please add it to the list of Wikis using Jmol.

How to use the Jmol Extension

Once the Jmol Extension is installed in the Wiki, you can start adding Jmol applets and controls.

How to know if the Extension is installed, and which version it is? Visit the Special:Version page in your wiki; the extension should be listed there.

Tags for simple link to Jmol models

These tags in a MediaWiki page generate a hyperlink that will open a new window (pop-up) filled with a JmolApplet. The applet will fit the window, which is resizable.

Tag <jmolFile>

This tag produces a link that opens a JmolApplet and loads the model from a file that has been previously uploaded to the wiki. The model is displayed in the default rendering (ball and stick, CPK color, black background).

The file must be uploaded to the wiki as if it were an image, using the "Upload file" link in the "Toolbox" panel on the left. Its location is hence [[File:MyMolecule.mol]], but only the name, MyMolecule.mol, must be inserted inside the <jmolFile> tag.

Examples:

<jmolFile>Chair.cml</jmolFile>

is rendered as Chair.cml which, when clicked, will open an applet with the model read from File:Chair.cml.

<jmolFile text="Show ethanol">Ethanol.xyz</jmolFile>

is rendered as Show ethanol which, when clicked, will open an applet with the model read from File:Ethanol.xyz.

Tag <jmolPdb>

This tag produces a link that opens a JmolApplet and loads the model from the RCSB PDB database server. The model is displayed in the default rendering (ball and stick, CPK color, black background).

Only the 4-character ID of the molecule in the PDB must be inserted inside the <jmolPdb> tag.

Examples:

<jmolPdb>2CDS</jmolPdb>

is rendered as 2CDS which, when clicked, will open an applet with the model retrieved from the PDB server.

<jmolPdb text="structure of lysozyme">2CDS</jmolPdb>

is rendered as structure of lysozyme which, when clicked, will open an applet with the model read from the PDB server.

Tag <jmolSmiles>

This tag produces a link that opens a JmolApplet and loads the model from the CACTUS NIH server, constructed from a SMILES string, CAS number, InChI key or chemical name. The model is displayed in the default rendering (ball and stick, CPK color, black background).

The name or key of the molecule must be inserted inside the <jmolSmiles> tag.

Examples:

<jmolSmiles>CCCNC</jmolSmiles>

is rendered as CCCNC which, when clicked, will open an applet with the propylmethylamine structure (of which CCCNC is the SMILES string) retrieved from the CACTUS server.

<jmolSmiles text="something for your headache">aspirin</jmolSmiles>

is rendered as something for your headache which, when clicked, will open an applet with the structure of aspirin read from the CACTUS server.

Tags that allow more control

Jmol applet in a MediaWiki page

To add a Jmol applet to a MediaWiki page, just add the following:

<jmol>
  <jmolApplet>
    <uploadedFileContents>name of file uploaded in the wiki containing the molecular data</uploadedFileContents>
  </jmolApplet>
</jmol>

The file must be uploaded to the wiki as if it were an image, using the "Upload file" link in the "Toolbox" panel on the left. Its location is hence [[Image:MyMolecule.mol]], but only the name, MyMolecule.mol, must be inserted inside the <uploadedFileContents> tags.

or

<jmol>
  <jmolApplet>
    <wikiPageContents>page of the wiki containing the molecular data</wikiPageContents>
  </jmolApplet>
</jmol>

or

<jmol>
  <jmolApplet>
    <inlineContents>contents of the molecular file</inlineContents>
  </jmolApplet>
</jmol>

or

<jmol>
  <jmolApplet>
    <urlContents>URL of the molecular file</urlContents>
  </jmolApplet>
</jmol>

If the file is in a server different than the wiki, you need to use the signed applet (<signed> tag).

Controls for the Jmol applet

To add a button to send scripts to the applet, just add the following:

<jmol>
  <jmolButton>
    <script>script to execute</script>
    <text>text of the button</text>
  </jmolButton>
</jmol>

To add a link to send scripts to the applet, just add the following:

<jmol>
  <jmolLink>
    <script>script to execute</script>
    <text>text of the link</text>
  </jmolLink>
</jmol>

To add a checkbox to send scripts to the applet, just add the following:

<jmol>
  <jmolCheckbox>
    <scriptWhenChecked>script to execute when the checkbox is checked</scriptWhenChecked>
    <scriptWhenUnchecked>script to execute when the checkbox is unchecked</scriptWhenUnchecked>
    <text>text of the checkbox</text>
  </jmolCheckbox>
</jmol>

To add a group of radio buttons to send scripts to the applet, just add the following:

<jmol>
  <jmolRadioGroup>
    <item>
      <script>script to execute when the radio button is selected</script>
      <text>text of the radio button</text>
    </item>
    <item>
      <script>script to execute when the radio button is selected</script>
      <text>text of the radio button</text>
    </item>
  </jmolRadioGroup>
</jmol>

To add a menu to send scripts to the applet, just add the following:

<jmol>
  <jmolMenu>
    <item>
      <script>script to execute when the menu item is selected</script>
      <text>text of the menu item</text>
    </item>
    <item>
      <script>script to execute when the menu item is selected</script>
      <text>text of the menu item</text>
    </item>
  </jmolMenu>
</jmol>

Applets and other controls can be combined in a single <jmol> tag.

Jmol applet in a popup window

To add a button that opens a new window containing a Jmol applet, use the <JmolAppletButton> tag instead of the <JmolApplet> tag and also add the <text> tag in it. For example:

<jmol>
  <jmolAppletButton>
    <uploadedFileContents>file uploaded in the wiki containing the molecular data</uploadedFileContents>
    <text>text displayed in the button</text>
  </jmolAppletButton>
</jmol>

To add a link that opens a new window containing a Jmol applet, use the <JmolAppletLink> tag instead of the <JmolApplet> tag and also add the <text> tag in it. For example:

<jmol>
  <jmolAppletLink>
    <uploadedFileContents>file uploaded in the wiki containing the molecular data</uploadedFileContents>
    <text>text displayed in the link</text>
  </jmolAppletLink>
</jmol>

In both cases, the new window will be resizable and the applet inside will resize with it.

(See also the simple tags above)

Reference

The <jmolFile>, <jmolPdb> and <jmolSmiles> tags just contain a string that specifies the model to be loaded. They may optionally include a text= attribute that will serve as the link; if omitted, the model string will also be used as the link text.

The <jmol> tag is more complex and will contain sub-tags like the following:

• <jmolApplet> : Jmol Applet.
  • <signed> (true, false) : To use the signed or unsigned version of the applet. This attribute can be disabled by the Wiki administrator with the $wgJmolAuthorizeChoosingSignedApplet setting in LocalSettings.php. Note that signed and unsigned applets cannot be mixed in the same page.
  • <color> : To set the background color of the Jmol applet (default is black). You can specify it:
    • With a named color belonging to the set that is recognized by Jmol.
    • With an hexadecimal value in the HTML fomat (e.g. #FF00CC).
    • With an hexadecimal value in the Jmol fomat (e.g. [xFF00CC]).
  • <uploadedFileContents> : Name of an uploaded file in this wiki containing the molecular data to load in the Jmol applet. The Wiki needs to be configured to authorize the upload of molecular data files (using $wgFileExtensions in LocalSettings.php). This attribute can be disabled by the Wiki administrator with the $wgJmolAuthorizeUploadedFile setting in LocalSettings.php.
  • <wikiPageContents> : Name of a page of this wiki containing the molecular data to load in the Jmol applet.
  • <urlContents> : URL of the molecular file to load. This attribute can be disabled by the Wiki administrator with the $wgJmolAuthorizeUrl setting in LocalSettings.php.
  • <inlineContents> : Molecular data to load in the Jmol applet.
  • <size> : Size of the applet. Only a number should be given, meaning pixels. Only square applets are currently suported (width=height).
  • <script> : Script to execute right after loading the molecule.
  • <name> : Name of the Jmol applet (useful if you want to use several Jmol applets in the same page).
• <jmolButton> : Button.
  • <script> : Jmol script to execute when the button is clicked.
  • <text> : Text of the button.
  • <name> : Name of the button.
  • <target> : Name of the Jmol applet linked with the button (useful only if you want to use several Jmol applets in the same page).
• <jmolLink> : Link. Same tags as <jmolButton>.
• <jmolCheckbox> : Checkbox.
  • <scriptWhenChecked> : Jmol script to execute when the checkbox is checked.
  • <scriptWhenUnchecked> : Jmol script to execute when the checkbox is unchecked.
  • <checked> (true, false) : Indicates if the checkbox is checked when the page loads.
  • <text> : Text displayed beside the checkbox.
  • <name> : Name of the checkbox object.
  • <target> : Name of the Jmol applet linked with the checkbox (useful only if you want to use several Jmol applets in the same page).
• <jmolMenu> : Menu.
  • <item> : Menu item.
    • <script> : Jmol script to execute when the menu item is selected.
    • <text> : Text of the menu item.
    • <checked> (true, false) : Indicates if the menu item is selected when the page loads.
  • <name> : Name of the menu object.
  • <target> : Name of the Jmol applet linked with the menu (useful only if you want to use several Jmol applets in the same page).
  • <menuHeight> : Number of visible menu items (1: combo-box, 2 or greater: list with the specified number of lines, -1: calculated). Default is 1.
• <jmolRadioGroup> : Group of radio buttons.
  • <item> : Radio button.
    • <script> : Jmol script to execute when the radio button is selected.
    • <text> : Text displayed beside the radio button.
    • <checked> (true, false) : Indicates if the radio button is checked when the page loads.
  • <name> : Name of the radio group.
  • <target> : Name of the Jmol applet linked with the radio group (useful only if you want to use several Jmol applets in the same page).
  • <vertical> (true, false) : Indicates if the radio buttons are stacked vertically or horizontally.
• <jmolAppletButton> : A button for opening a new window containing a Jmol Applet. It can contain the same tags as the <jmolApplet> tag, and also the following tags :
  • <title> : Title of the new window. Defaults to "Jmol".
  • <text> : Text of the button. Defaults to the contents of <title>.
  • <x> and <y> : Position of the new window.
• <jmolAppletLink> : A link for opening a new window containing a Jmol Applet. Same tags as <jmolAppletButton>.

Test Pages

1. A demo page
2. Uploaded XYZ File -- includes test of jmolCheckbox, jmolLink, jmolButton, and jmolMenu
3. Uploaded MDL Molfile
4. Uploaded CML File
5. Uploaded PDB File opening in a pop-up -- tests jmolAppletLink
6. Inlined MDL Molfile
7. Inlined PDB File
8. Inlined CML File
9. Load SMILES via script -- Includes test of signed applet and jmolMenu
10. Test page (Brian's)

Installation

(This must be done by the wiki administrator.)

Installation of the Jmol extension is now described on the Jmol extension page on MediaWiki.

You can configure the Jmol extension with several settings added after the above line (default value in bold):

• $wgJmolAuthorizeChoosingSignedApplet (true, false) : Authorize users to choose between the unsigned and the signed Jmol applet.
• $wgJmolAuthorizeUploadedFile (true, false) : Authorize the use of <uploadedFileContents>.
• $wgJmolAuthorizeUrl (true, false) : Authorize the use of <urlContents>.
• $wgJmolDefaultAppletSize (400) : Size in pixels of the Jmol applet.
• $wgJmolDefaultScript : Default script.
• $wgJmolExtensionPath (extensions/Jmol) : Path to the directory where the Jmol extension is installed. This must be an absolute path, therefore if you customize it, make sure it is prepended with $wgScriptPath (see example in Jmol.php).
• $wgJmolForceNameSpace : Force the NameSpace where the applet will go looking for wiki pages containing molecular data (using <wikiPageContents>).
• $wgJmolShowWarnings (true, false) : Display warnings when users try to use disabled features.
• $wgJmolUsingSignedAppletByDefault (true, false) : Choose if the signed Jmol applet will be used by default. Note: the signed Jmol applet is signed with a default certificate. If you want to use the signed Jmol applet in your wiki, I suggest resigning the Jmol applet with your own certificate.

Note: If you want to authorize users to upload files containing molecular data (for using the <uploadedFileContents> tag), you need to do the following:

• By default, MediaWiki authorizes the uploading of files whose name ends with a limited number of extensions. For example, if you want to authorize uploading *.cml files, add $wgFileExtensions[] = 'cml'; in LocalSettings.php.
• You can add an icon in the skins/common/images/icons/ directory for each extension (for example, fileicon-cml.png). In this wiki, we are using this image, which leads to the following result.

Installation of older versions

The Jmol Extension below v. 3.3 uses another extension, Stub Manager, so you first need to install it.

Problems yet to be solved

• Having problems with Jmol applets that are placed below the flow of a link, button, or other user interface element in markup. I get what appears to be a Java error when loading an uploaded file. --Mevans86 18:58, 13 October 2010 (UTC)

• Does not work with Media wiki 1.17 (and probably 1.15,1.16). I think there was a rewrite of mediawiki code and I get:

Warning: Parameter 1 to Jmol::tag_jmol() expected to be a reference, value given in /var/www/mediawiki/extensions/StubManager/StubManager.php on line 783

--Jacksmind 01:00, 10 October 2010 (UTC)

Hopefully this is solved with version 3.3 of the Extension, since it no longer depends on StubManager. (Still to be confirmed, but it is working fine with MW 1.16 in this site.) --AngelHerraez 12:32, 22 November 2010 (CET)

• The developers at WikiMedia / WikiMedia Commons / Wikipedia apparently advocate the use of a simpler way of inserting Jmol applets, by just linking to the (previously uploaded) model file (as it is done e.g. with images) and having the server decide upon the way to handle it, with something simpler than the current Extension (see a discussion about this).

However, in my opinion rendering of a 3D molecular model clearly calls for something more flexible than a simple, barebone viewer with default settings. Maybe we would have to resort to a simpler extension for Wikipedia and a full one for other wikis?

New tags are available since version 3.3 of the extension, which are much more simple to use (<jmolFile>, <jmolPdb>, <jmolSmiles>), but are currently not flexible. A solution to explore may be the use of HTML templates to give the opporunity to choose between differently configured viewers (with different controls and informations). --NicolasVervelle 22:44, 28 November 2010 (CET)

• An interesting feature would be the server-side automation of the snapshot ability of the Jmol application, so that images are generated into the wiki page as a thumbnail that will link to --or be replaced by-- the applet when the user clicks on the image, or on a link below it (see an example of this idea, though not server-generated).

Already solved

These are left here for reference, as you may still have these problems depending on your version of MediaWiki or your version of the Jmol MediaWiki Extension.

• The installation does not work when the wiki is installed in a non-root folder of the server (e.g. http://www.myserver.com/mywiki/index.php instead of http://mywiki.myserver.com/index.php).

Fixed (2008-Nov-29) in revision 10393.

• Using <jmolAppletButton> or <jmolAppletlink> throws an error in Internet Explorer: "Invalid argument", and prevents the pop-up.

Partially fixed (2008-Dec-2) in revision 10411.

Completely fixed (2008-Dec-8) in revision 10467.

• The scripts associated to checkboxes rendered by <jmolCheckbox> have no effect on the applet.

Fixed (2008-Dec-8) in revision 10467.

This was the discussion of the problem:

(Bob) something in /skins/common/wikibits.js?97 is disabling checkboxes.
(Nico) Yes, good catch, thanks a lot. Now, I need to find a way to overcome the behaviour of setupCheckboxShiftClick(). I am going to ask on mediawiki list.
(Bugzilla) discussion

The problem was due to a conflict in the onClick event for checkboxes correctly written by the Jmol Extension and a javascript library (wikibits.js) included in MediaWiki. The offending js function is now overwritten by the extension.

• Since Jmol scripting can include a call to javascript commands, the Jmol applet inserted by the Jmol MediaWiki Extension can execute arbitrary javascript added by any user editing the page (see demo). This is an unacceptable security hole for some systems such as Wikipedia, and will prevent Jmol from being used there. There is hence a need to implement a "scripting-without-javascript" mode of the applet, i.e. a way to completely disable the javascript command in Jmol scripts run from the MediaWiki Extension.

Fixed (2008-Dec-8) in revision 10467.

No javascript will be executed by Jmol applets inserted by the Extension.

• The signed applet was not being used even when explicitly authorized in the wiki configuration ($wgJmolAuthorizeChoosingSignedApplet=true) and requested for the applet (<signed>true</signed>).

Fixed (2008-Dec-8) in revision 10467.

Now you can also have both signed and unsigned applets in the same page.

• Inserting applets with models read from php pages fails. The applet is using the <urlContents> tag and the url contains the '&' character.

Fixed (2009-Nov-13) in revision 11738, version 3.2 of the Extension.

The '&' is not tolerated by the wikicode. The solution is to use %26 (the wikicode for &) instead of the ampersand(s) in the url, content of the <urlContents> tag. The Extension will later filter those %26 codes and convert them to & so that the server correctly provides the model.

External links

• Wikipedia: Using Jmol to display molecular models
• Wikipedia: WikiProject Chemistry
• MediaWiki: Jmol Extension for MediaWiki

Contributors

AngelHerraez, NicolasVervelle, Rzepa, Mevans86, Ngreeves, Pimpim, SklogWiki, Jacksmind, EricMartz