Extension:Jmol

Jmol extension is an extension for displaying molecular models in interactive 3d inside MediaWiki articles 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 &lt;jmolFile&gt;
The &lt;jmolFile&gt; tag can be used to display in 3d a molecule file that has been previously uploaded into Wikipedia. Some examples of its usage are available in the Jmol wiki. This tag is only available if authorized in the configuration ($wgJmolAuthorizeJmolFileTag set to true which is the default configuration).

A few examples:
 *  Chair.cml  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 File:Chair.cml.
 *  Chair.cml</jmolFile> </tt> 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 File:Chair.cml</tt>.

The following attributes are available for the &lt;jmolFile&gt;</tt> tag:
 * text: To configure the text used for the link. By default, the file name is used for the link.

Tag &lt;jmolSmiles&gt;</tt>
The &lt;jmolSmiles&gt;</tt> 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 ($wgJmolAuthorizeJmolSmilesTag</tt> set to true</tt> which is the default configuration).

A few examples:
 *  <jmolSmiles>CCCNC</jmolSmiles> </tt> 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.
 *  <jmolSmiles text="Smiles">CCCNC</jmolSmiles> </tt> 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 &lt;jmolSmiles&gt;</tt> tag:
 * text: To configure the text used for the link. By default, the SMILES string is used for the link.

Tag &lt;jmolPdb&gt;</tt>
The &lt;jmolPdb&gt;</tt> 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 ($wgJmolAuthorizeJmolPdbTag</tt> set to true</tt> which is the default configuration).

A few examples:
 *  <jmolPdb>1ALE</jmolPdb> </tt> 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.
 *  <jmolPdb text="Show 1ALE">1ALE</jmolPdb> </tt> 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 &lt;jmolPdb&gt;</tt> tag:
 * text: To configure the text used for the link. By default, the PDB code is used for the link.

Tag <tt>&lt;jmol&gt;</tt>
The <tt>&lt;jmol&gt;</tt> 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 (<tt>$wgJmolAuthorizeJmolTag</tt> set to <tt>true</tt> which is the default configuration).

Installing Jmol extension
Note: The latest version of the Jmol extension has been tested against MediaWiki 1.16. It probably works also with some earlier versions but this has not been tested.

To install the Jmol extension:
 * Create a <tt>Jmol</tt> folder in the <tt>extensions</tt> folder of your MediaWiki installation.
 * Download the latest stable release of Jmol (or the latest development release).
 * Extract into the <tt>Jmol</tt> folder the following files from the Jmol release :
 * all the <tt>*.txt</tt> files,
 * the <tt>Jmol.js</tt> file,
 * all the <tt>JmolApplet0*.jar</tt>,
 * all the <tt>JmolAppletSigned0*.jar</tt> files, if you want to be able to use the signed applet (this is necessary for some tags, see description in the following chapters). The certificate used to sign the files is auto-signed, so you may wish to resign them with an authentic certificate.
 * Download all the source files of the Jmol extension and place them in the <tt>Jmol</tt> folder.
 * 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
 * Manual:Image Administration

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 (<tt>*.cml</tt>), you can add the following line in your LocalSettings.php file: 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 (<tt>text/plain</tt>, <tt>application/xml</tt>, …). 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 (<tt>*.cml</tt>), 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 <tt>includes/mime.types</tt> 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, <tt>*.cml</tt> can be detected as <tt>chemical/x-cml</tt> or <tt>application/xml</tt> (depending on your MIME type detection configuration), so you need to make the following additions to <tt>includes/mime.types</tt>: application/xml xml xsl xsd cml chemical/x-cml cml

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 <tt>skins/common/images/icons</tt> folder for each extension for molecular files (for example <tt>fileicon-cml.png</tt>). You can use.

Configuration
There are some options you can specify in your LocalSettings.php file (after the <tt>require_once</tt> line you've already added): Note: This list is not complete.
 * wgJmolAuthorizeJmolTag: Authorize the use of the <tt> </tt> tag. Default is <tt>true</tt>.
 * wgJmolAuthorizeJmolFileTag: Authorize the use of the <tt> <jmolFile/> </tt> tag. Default is <tt>true</tt>.
 * wgJmolAuthorizeJmolPdbTag: Authorize the use of the <tt> <jmolPdb/> </tt> tag. Default is <tt>true</tt>. Note: this tag requires the signed applet to be installed.
 * wgJmolAuthorizeJmolSmilesTag: Authorize the use of the <tt> <jmolSmiles/> </tt> tag. Default is <tt>true</tt>. Note: this tag requires the signed applet to be installed.

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