Extension:Jmol

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
Jmol

Release status: beta

Jmol screenshot streptavidin.png
Implementation Tag
Description Displaying molecular models in interactive 3d (using Jmol applets)
Author(s) NicoVtalk
MediaWiki 1.16+
License GNU Lesser General Public License
Download Subversion
Example Basic, complex
Parameters

$wgJmolAuthorizeJmolFileTag
$wgJmolAuthorizeJmolPdbTag
$wgJmolAuthorizeJmolSmilesTag
$wgJmolAuthorizeJmolTag

Tags
jmol

jmolFile
jmolPdb
jmolSmiles

Hooks used
ParserFirstCallInit

Translate the Jmol extension if possible

Check usage and version matrix; code metrics

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[edit | edit source]

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[edit | edit source]

Not yet implemented


Tag <jmolFile>[edit | edit source]

The <jmolFile> 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:

  • <jmolFile>Chair.cml</jmolFile> 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.
  • <jmolFile text="Chair">Chair.cml</jmolFile> 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.


The following attributes are available for the <jmolFile> tag:

  • text: To configure the text used for the link. By default, the file name is used for the link.


Tag <jmolSmiles>[edit | edit source]

The <jmolSmiles> 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 set to true which is the default configuration).


A few examples:

  • <jmolSmiles>CCCNC</jmolSmiles> 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> 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 <jmolSmiles> tag:

  • text: To configure the text used for the link. By default, the SMILES string is used for the link.


Tag <jmolPdb>[edit | edit source]

The <jmolPdb> 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 set to true which is the default configuration).


A few examples:

  • <jmolPdb>1ALE</jmolPdb> 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> 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 <jmolPdb> tag:

  • text: To configure the text used for the link. By default, the PDB code is used for the link.


Tag <jmol>[edit | edit source]

The <jmol> 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 ($wgJmolAuthorizeJmolTag set to true which is the default configuration).

Installing Jmol extension[edit | edit source]

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 Jmol folder in the extensions folder of your MediaWiki installation.
  • Download the latest stable release of Jmol (or the latest development release).
  • Extract into the Jmol folder the following files from the Jmol release :
    • all the *.txt files,
    • the Jmol.js file,
    • all the JmolApplet0*.jar,
    • all the JmolAppletSigned0*.jar 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 Jmol folder.
  • Add the following line to your LocalSettings.php file (near the end):
require_once("extensions/Jmol/Jmol.php");


Managing molecular files[edit | edit source]

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:


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 (*.cml), you can add the following line in your LocalSettings.php file:

$wgFileExtensions[] = 'cml';

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 (text/plain, application/xml, …). 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 (*.cml), you can add the following lines in your LocalSettings.php file:

$wgXMLMimeTypes = array_merge( $wgXMLMimeTypes, array(
	'http://www.xml-cml.org/schema:cml'                => 'chemical/x-cml',
	'http://www.xml-cml.org/schema:molecule'           => 'chemical/x-cml',
	'http://www.xml-cml.org/schema/cml2/core:list'     => 'chemical/x-cml',
	'http://www.xml-cml.org/schema/cml2/core:molecule' => 'chemical/x-cml' ) );


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 includes/mime.types 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, *.cml can be detected as chemical/x-cml or application/xml (depending on your MIME type detection configuration), so you need to make the following additions to includes/mime.types:

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

Configuration[edit | edit source]

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

wgJmolAuthorizeJmolTag
Authorize the use of the <jmol/> tag. Default is true.
wgJmolAuthorizeJmolFileTag
Authorize the use of the <jmolFile/> tag. Default is true.
wgJmolAuthorizeJmolPdbTag
Authorize the use of the <jmolPdb/> tag. Default is true. Note: this tag requires the signed applet to be installed.
wgJmolAuthorizeJmolSmilesTag
Authorize the use of the <jmolSmiles/> tag. Default is true. Note: this tag requires the signed applet to be installed.

Note: This list is not complete.

Wikis using the Jmol extension[edit | edit source]

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

Troubleshooting[edit | edit source]

Options in LocalSettings.php have no effect[edit | edit source]

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

Weblinks[edit | edit source]