MediaWiki/ExtensionV4

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.

Jmol MediaWiki Extension (version 4)

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

Please check the version you have installed in your wiki (browse to Special pages, then Version). Documentation for former versions of the Extension may be found in MediaWiki/ExtensionV3.

There are 3 ways to use Jmol models (JSmol or Jmol-Java) in a wiki that implements this extension:

1. In-page models: Inserting a Jmol object within the page content, allowing scripts and custom rendering. Additionally, inserting controls that will act on the Jmol object (links, buttons, radio buttons, menus... that will apply scripts to the model).
2. Popup calls: Inserting a link or a button that will open a Jmol model in a popup window, allowing scripts and custom rendering.
3. Simple calls: Inserting a link that will open a Jmol model in a popup window, with no custom rendering, no scripting.

In-page models

Tag <jmolApplet>

This tag in a MediaWiki page inserts a Jmol object (by default the JSmol HTML5 modality). It may be complemented with the insertion of controls that will apply some scripting on the model (next section).

The tag and its complements must be enclosed in an enveloping <jmol> tag. All these tags and sub-tags must open (<keyword>) and close (</keyword>) and in between contain the information.

To insert a Jmol object into a MediaWiki page, start with the following:

<jmol>
  <jmolApplet>
    ...(additional information using sub-tags, read below)
  </jmolApplet>
</jmol>

Sub-tags for model sources

The model data may come from one of several sources, and is specified in a subtag inside the <jmolApplet> tag:

• A file uploaded in the wiki, containing the molecular data:

<jmol>
  <jmolApplet>
    <uploadedFileContents> name of file in the wiki </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> tag.

Admin:

This possibility can be globally disabled by the Wiki administrator with the $wgJmolAuthorizeUploadedFile setting. If it is enabled, the Wiki needs to be configured to authorize the upload of molecular data files, using $wgFileExtensions. Both settings are in LocalSettings.php.

• A page of the wiki which contains as text the molecular data:

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

• The contents of the molecular data, written inside the tag:

<jmol>
  <jmolApplet>
    <inlineContents> the molecular data </inlineContents>
  </jmolApplet>
</jmol>

• An external file located anywhere in the web:

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

Admin:

This possibility can be globally disabled by the Wiki administrator with the $wgJmolAuthorizeUrl setting in LocalSettings.php.

If the file is in a server different than the wiki, you need to have jsmol.php properly configured in your wiki server setup (see serverURL)

Sub-tags for features of the Jmol object

• <color> Sets the background color of the Jmol object (default is white). You can specify it:
  • With a named color belonging to the set that is recognized by Jmol (e.g. paleGoldenrod).
  • With an hexadecimal value in the HTML format (e.g. #EEE8AA).
  • With an hexadecimal value in the JmolScript fomat (e.g. [xEEE8AA]).
• <size> Size of the applet. Only a number should be given, meaning pixels. Only square applets are currently suported (width=height).
• <float> left or right
• <frame> if true, draws a frame around the Jmol object.
• <title> Text displayed above the Jmol object.
• <titlecss> CSS style for the title.
• <caption> Text displayed below the Jmol object. Be careful with formatting or special characters; must be enabled for wikitext, i.e. you can include double square bracket links.
• <captioncss> CSS style for the caption.
• <controls> Inserts some utility control buttons below the Jmol object; values may be all | spin | quality | popup
• <script> Jmol commands to execute right after loading the molecule.
• <name> When a page includes several Jmol objects, this name allows to associate action of Jmol controls to this particular Jmol object (via a matching <target> in those controls).
• <pspeed> Platform speed parameter for Jmol (numeric from 1 to 8)
• <animgifurl> URL of an animated GIF file to display before rendering the model.

Examples

wikitext code:	result:
<jmol> <jmolApplet> <name>Jmol_A</name> <title>Cyclohexane</title> <caption>Chair conformation</caption> <float>right</float> <color>blueTint</color> <size>250</size> <uploadedFileContents>Chair.xyz</uploadedFileContents> <pspeed>2</pspeed> <controls>spin popup</controls> </jmolApplet> </jmol> Note: excess spaces inside the tags may prevent proper operation.	Cyclohexane Chair conformation

Tags for controls acting on the Jmol object

Each type of control has specific options as sub-tags, but all should include a text to be displayed in the control and a script of Jmol commands. If the text is omitted, it will be a (shortened) copy of the script.

Tags for controls may be included within their own, separate <jmol> tag or be combined with the <jmolApplet> under a single <jmol> tag.

The <target> sub-tag is useful only when the page includes more than one Jmol object, and must match the respective <name> sub-tag of the <jmolApplet> tag.

Tag <jmolButton>

<jmol>
  <jmolButton>
    <script> script to execute when the button is pressed </script>
    <text> text displayed in the button </text>
    <name> html name of the button </name>
    <target> name of the Jmol object on which the script will be applied </target>
  </jmolButton>
</jmol>

Tag <jmolLink>

<jmol>
  <jmolLink>
    <script> script to execute when the link is clicked </script>
    <text> text displayed in the link </text>
    <name> html name of the <a> element </name>
    <target> name of the Jmol object on which the script will be applied </target>
  </jmolLink>
</jmol>

Tag <jmolCheckbox>

<jmol>
  <jmolCheckbox>
    <scriptWhenChecked> script to execute when the checkbox is checked </scriptWhenChecked>
    <scriptWhenUnchecked> script to execute when the checkbox is unchecked </scriptWhenUnchecked>
    <checked> true </checked> 
    <text> text beside the checkbox </text>
    <name> html name of the checkbox element </name>
    <target> name of the Jmol object on which the scripts will be applied </target>
  </jmolCheckbox>
</jmol>

<checked> indicates if the checkbox is initially checked when the page loads (default is false).

Tag <jmolRadioGroup>

Inserts a group of mutually exclusive radio buttons.

<jmol>
  <jmolRadioGroup>
    <vertical> true or false </vertical>
    <name> html name of the radio group </name>
    <target> name of the Jmol object on which the scripts will be applied </target>
    <item>
      <script> script to execute when first radio button is selected </script>
      <text> text displayed beside first radio button </text>
      <checked> true </checked>
    </item>
    <item>
      <script> script to execute when second radio button is selected </script>
      <text> text displayed beside second radio button </text>
    </item>
  </jmolRadioGroup>
</jmol>

<vertical> indicates if the radio buttons are stacked vertically (separated by line break) or horizontally (separated by space).

<checked> indicates that particular (item) radio button is initially checked when the page loads (default is false).

Tag <jmolMenu>

<jmol>
  <jmolMenu>
    <menuHeight> number </menuHeight> 
    <name> html name of the menu object </name>
    <target> name of the Jmol object on which the scripts will be applied </target>
    <item>
      <script> script to execute when first menu item is selected </script>
      <text> text of first menu item </text>
      <checked> true </checked>
    </item>
    <item>
      <script> script to execute when second menu item is selected </script>
      <text> text of second menu item </text>
    </item>
  </jmolMenu>
</jmol>

The value in <menuHeight> is the number of visible menu options (if 2 or more). 1 (the default) gives a combo-box. -1 expands to make all options visible.

<checked> indicates that particular (item) option is initially selected when the page loads (default is the first option in the menu).

Popup calls

These tags in a MediaWiki page generate a hyperlink or a button 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.

These tags use the same method as the <jmolApplet> tag described in the previous section, and can contain the same sub-tags (if applicable). Hence, description and examples here are minimal.

The tags must be enclosed in an enveloping <jmol> tag, which may also enclose additional tags to achieve custom rendering styles and any scripting.

The model data may come from one of several sources, same as for the <jmolApplet> (described above).

Tag <jmolAppletButton>

<jmol>
  <jmolAppletButton>
    <uploadedFileContents> file uploaded in the wiki containing the molecular data </uploadedFileContents>
    <title> text displayed as title of the popup window </title>
    <text> text displayed in the button </text>
    <x> number of pixels </x>
    <y> number of pixels </y>
  </jmolAppletButton>
</jmol>

<title> defaults to "Jmol".

<text> defaults to the contents of <title>.

<x> sets the horizontal position of the popup window.

<y> sets the vertical position of the popup window.

Tag <jmolAppletLink>

<jmol>
  <jmolAppletLink>
    <uploadedFileContents> file uploaded in the wiki containing the molecular data </uploadedFileContents>
    <title> text displayed as title of the popup window </title>
    <text> text displayed in the link </text>
    <x> number of pixels </x>
    <y> number of pixels </y>
  </jmolAppletLink>
</jmol>

<title> defaults to "Jmol".

<text> defaults to the contents of <title>.

<x> sets the horizontal position of the popup window.

<y> sets the vertical position of the popup window.

Simple calls

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. No custom rendering styles or scripting can be applied to the model.

The model data may come from one of 3 sources:

1. a file that has been previously uploaded to the wiki;
2. a file retrieved from the RCSB PDB database server (macromolecules);
3. a file retrieved from the CACTUS NIH server.

All 3 tags need to include just a string that specifies the model to be loaded (file name or ID). They may optionally include a text= attribute that will serve as the visible text making the link; if omitted, the model string will also be used as the link text.

Note that these tags do not require a <jmol> tag (in contrast to the tags described in the preceding sections).

Tag <jmolFile>

This tag produces a link that opens a popup 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, white 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.

Admin:

This possibility can be globally disabled by the Wiki administrator with the $wgJmolAuthorizeUploadedFile setting. If it is enabled, the Wiki needs to be configured to authorize the upload of molecular data files, using $wgFileExtensions. Both settings are in LocalSettings.php.

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, white 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, white 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.

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