MediaWiki/ExtensionV3

Jmol MediaWiki Extension (version 3)

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.

General information on this Extension and its setup in the MediaWiki page.

This documentation applies to an old version of the Extension. For the most current one, please visit MediaWiki/ExtensionV4.

Please check the version you have installed in your wiki (browse to Special pages, then Version).

All this refers to Jmol Objects (either Java applets or JSmol HTML5).

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 Jmol object (by default the JSmol HTML5 modality). The Jmol object will fit the window, which is resizable.

Tag <jmolFile>

This tag produces a link that opens a Jmol object 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 a Jmol object 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 a Jmol object with the model read from File:Ethanol.xyz.

Tag <jmolPdb>

This tag produces a link that opens a Jmol object 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 a Jmol object 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 a Jmol object with the model read from the PDB server.

Tag <jmolSmiles>

This tag produces a link that opens a Jmol object 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 a Jmol object 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 a Jmol object with the structure of aspirin read from the CACTUS server.

Tags that allow more control

Jmol object in a MediaWiki page

To add a Jmol object 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 object

To add a button that sends a script to Jmol, just add the following:

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

To add a link that sends a script to Jmol, just add the following:

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

To add a checkbox that sends scripts to Jmol, 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 that send scripts to Jmol, 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 that sends scripts to Jmol, 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>

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

Jmol object in a popup window

To add a button that opens a new window containing a Jmol object, 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 object, 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 Jmol object 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 object.
  • <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 object (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 object. 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 object.
  • <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 object.
  • <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 object (useful if you want to use several Jmol objects 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 object linked with the button (useful only if you want to use several Jmol objects 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 object linked with the checkbox (useful only if you want to use several Jmol objects 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 object 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 object linked with the radio group (useful only if you want to use several Jmol objects 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 object. 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 object. Same tags as <jmolAppletButton>.

Test Pages

1. A few basic examples of the <jmolFile>, <jmolPdb> and <jmolSmiles> tags.
2. A demo page for the <jmol> tag
3. Uploaded XYZ File -- includes test of <jmolCheckbox>, <jmolLink>, <jmolButton>, and <jmolMenu>
4. Uploaded MDL Molfile
5. Uploaded CML File
6. Uploaded PDB File opening in a pop-up -- tests jmolAppletLink
7. Inlined MDL Molfile
8. Inlined PDB File
9. Inlined CML File
10. Load SMILES via script -- Includes test of signed applet and <jmolMenu>
11. Test page (Brian's)

Contributors

AngelHerraez