Extension:Jmol

The Jmol extension allows for displaying molecular models in interactive 3d inside wiki pages using Jmol applets.

Previous documentation can be found on the Jmol wiki.

Usage
The Jmol extension can be used in several ways:
 * directly in the media pages of molecular files,
 * as a "custom tag" to display a molecule in 3d in-line (or in a popup window) on a wiki page.

Media pages
Not yet implemented

Tag
The  tag can be used to display in 3d a molecule file that has been previously uploaded into a Wiki. Some examples of its usage are available in the Jmol wiki. This tag is only available if authorized in the configuration ( set to   which is the default configuration).

A few examples:
 * will add a link named Chair.cml to the article. When this link is clicked on, a popup window is displayed containing a Jmol applet with the molecular file.
 * will add a link named Chair to the article. When this link is clicked on, a popup window is displayed containing a Jmol applet with the molecular file.

The following attributes are available for the  tag:
 * text: To configure the text used for the link. By default, the file name is used for the link.

Tag
The  tag can be used to display in 3d a molecule file using its SMILES notation. Some examples of its usage are available in the Jmol wiki. This tag is only available if authorized in the configuration ( set to   which is the default configuration).

A few examples:
 * will add a link named CCCNC to the article. When this link is clicked on, a popup window is displayed containing a Jmol applet with a molecular file matching the SMILES string CCCNC.
 * will add a link named Smiles to the article. When this link is clicked on, a popup window is displayed containing a Jmol applet with a molecular file matching the SMILES string CCCNC.

The following attributes are available for the  tag:
 * text: To configure the text used for the link. By default, the SMILES string is used for the link.

Tag
The  tag can be used to display in 3d a molecule file using its PDB code. Some examples of its usage are available in the Jmol wiki. This tag is only available if authorized in the configuration ( set to   which is the default configuration).

A few examples:
 * will add a link named 1ALE to the article. When this link is clicked on, a popup window is displayed containing a Jmol applet with a molecular file matching the PDB code 1ALE.
 * will add a link named Show 1ALE to the article. When this link is clicked on, a popup window is displayed containing a Jmol applet with a molecular file matching the PDB code 1ALE.

The following attributes are available for the  tag:
 * text: To configure the text used for the link. By default, the PDB code is used for the link.

Tag
The  tag can be used to display in 3d a molecule file in several situations. Its use is more complex than the other tags, but also more flexible. The documentation for this tag is currently available in the Jmol wiki. This tag is only available if authorized in the configuration ( set to   which is the default configuration).

Installing Jmol extension
Note: Version 5 of the Jmol Extension has been tested against MediaWiki 1.32. There are significant changes in MediaWiki, so this procedure will not work with older versions.

To install the Jmol extension:
 * 1) Download the latest release of Jmol  You need version 14.29.32 or later.
 * 2) Extract into a temporary location the   file from the Jmol release.
 * 3) Create a   folder in the   folder of your MediaWiki installation.
 * 4) Extract into this   folder the following contents from the   file:
 * 5) * the  file,
 * 6) * the  file,
 * 7) * the,   and   folders.
 * 8) If you want users to have the option of using the Java applet modality of Jmol:
 * 9) create a   subfolder inside the   folder
 * 10) go back to the Jmol release   file and extract from its   folder all files which name starts with   (that's currently 23 files)
 * 11) Download all the source files of the Jmol extension and place them in the   folder.
 * 12) Add the following line to your LocalSettings.php file (near the end):

Managing molecular files
MediaWiki authorizes the uploading of a very limited set of file types, based on file extensions and MIME types. By default, uploading molecular files is not authorized, so the configuration must be modified to take advantage of all the Jmol extension features.

Configuration of file uploading for MediaWiki can be quite complex and may also depend on the servers configuration hosting the wiki. You can read several MediaWiki manual pages for correctly configuring file uploading for your own MediaWiki setup:
 * Manual:Configuring file uploads
 * Manual:Mime type detection

First, you need to authorize new file extensions being uploaded in the wiki, using $wgFileExtensions.

For example, if you want to authorize uploading of CML files, you can add the following line in your LocalSettings.php file:

Suggestion for other molecular file types:

You can check what file extensions are authorized in the Special:Upload page.

By default, the MIME type detection configuration of MediaWiki only detects molecular files as basic MIME types (,  , …). Having a more precise MIME type detection is better, especially for the Media Handler.

For molecular files formats based on XML, the MIME type detection can be enhanced using $wgXMLMimeTypes which allows the mapping between the root element of the file and the MIME type.

For example, for enhancing detection for CML files, you can add the following lines in your LocalSettings.php file:

Note: This description needs to be completed, especially for dealing with MIME types which is quite complex and depends on your server configuration.

By default, MediaWiki checks that the file extension matches the MIME type that has been detected. For this, MediaWiki uses the  file in MediaWiki installation. File extensions for molecular models are probably missing from this file by default, so you need to modify it.

For example,  can be detected as   or   (depending on your MIME type detection configuration), so you need to make the following additions to  : application/xml xml xsl xsd cml chemical/x-cml cml

Suggestion for other molecular file types (taken from The Chemical MIME Home Page): chemical/x-xyz xyz chemical/x-mdl-molfile mol chemical/x-pdb pdb Alternativley, all 3 might be added to MIME type

Now that new file extensions being uploaded have been authorized, you can do a last modification so that molecular files are shown with a specific icon in categories (see example on the Jmol wiki). You can add an icon in the  folder for each extension for molecular files (for example  ). You can use.

Configuration
There are some options you can specify in your LocalSettings.php file (after the  line you've already added):

Note: This list is not complete.


 * wgJmolAuthorizeJmolTag: Authorize the use of the  tag. Default is.
 * wgJmolAuthorizeJmolFileTag: Authorize the use of the  tag. Default is.
 * wgJmolAuthorizeJmolPdbTag: Authorize the use of the  tag. Default is.
 * wgJmolAuthorizeJmolMolTag: Authorize the use of the  tag. Default is.
 * wgJmolAuthorizeJmolSmilesTag: Authorize the use of the  tag. Default is.
 * wgJmolPdbServer: specifies the server and url where pdb-formatted files will be retrieved from (to be used by the  tag). The url must include   that will be replaced by the 4-character PDB ID. Default is to retrieve the gzipped pdb-format file from the RCSB server. Values for other known servers can be seen (commented out) in the   file.
 * wgJmolMolServer: specifies the server and url where mol-formatted files will be retrieved from (to be used by the  tag). The url must include   that will be replaced by the name of the molecule. The default is to use the Jmol method for retrieving files via the Chemical Identifier Resolver (Cactus server), NCI/CADD Group, NIH (i.e. it uses   which is internally converted to the proper url by Jmol/Jsmol)

Wikis using the Jmol extension
If you know a wiki using the Jmol extension, please add it to the list of Wikis using Jmol.

Options in LocalSettings.php have no effect

 * Make sure you specify the options after including the extension.

Weblinks

 * Jmol official web site
 * Jmol official Wiki
 * Browse extension source code
 * Extension documentation in Jmol Wiki