User:AngelHerraez/Sandbox MW Extension

The Jmol extension allows for displaying molecular models in interactive 3D inside wiki pages using JSmol HTML5 objects.

Documentation on its installation and use can be found at the Jmol project pages, as well as at Jmol Wiki, with full details and demonstration examples.

Usage

The Jmol extension can be used as a "custom tag" to display a 3D interactive view of a molecule or structure in a wiki page, either:

• in-line, inserted in the page as the page is loaded
• in-line, inserted in the page upon user action
• in a popup window, upon user action

<jmolFile>

The <jmolFile> tag can be used to display in 3D a molecule or structure file that has been previously uploaded into a Wiki. This tag may be disabled by administrators in the configuration file of the wiki ($wgJmolAuthorizeJmolFileTag = false.

A few examples:

• <source lang=html inline>Chair.cml</source> will put in the article a Chair.cml link. When this link is clicked on, a popup window will display the 3D structure specified in File:Chair.cml.
• <source lang=html inline>chair conformation</source> will put in the article a chair conformation link. When this link is clicked on, a popup window will display the 3D structure specified in File:Chair.cml.

<jmolSmiles>

The <jmolSmiles> tag can be used to display in 3D a molecule file using its SMILES notation. This tag may be disabled by administrators in the configuration file of the wiki ($wgJmolAuthorizeJmolSmilesTag = false.

A few examples:

• <source lang=html inline>CCCNC</source> will put in the article a CCCNC link. When this link is clicked on, a popup window will display the 3D structure that matches the SMILES string CCCNC.
• <source lang=html inline>smiles notation</source> will put in the article a smiles notation link. When this link is clicked on, a popup window will display the 3D structure that matches the SMILES string CCCNC.

<jmolPdb>

The <jmolPdb> tag can be used to display in 3D a molecule file using its PDB code. This tag may be disabled by administrators in the configuration file of the wiki ($wgJmolAuthorizeJmolPdbTag = false.

A few examples:

• <source lang=html inline>1ALE</source> will put in the article a 1ALE link. When this link is clicked on, a popup window will display the 3D structure matching the PDB code 1ALE.
• <source lang=html inline>Show 1ALE</source> will put in the article a Show 1ALE link. When this link is clicked on, a popup window will display the 3D structure matching the PDB code 1ALE.

<jmol>

The <jmol> tag can be used to display in 3D a molecule or structure file in several situations. Its use is more complex than the other tags, but also more flexible. It takes embedded sub-tags (2nd and 3rd level). Documentation is available in the Jmol project pages or in the Extension page at the Jmol Wiki This tag may be disabled by administrators in the configuration file of the wiki ($wgJmolAuthorizeJmolTag = false.

Installing Jmol extension

File:Jmol Extension 6 folders setup.jpg

arrangement of folders and files of the Jmol Extension

Note: Version 6 of the Jmol Extension has been tested against MediaWiki 1.39-1.43. For older installations of MediaWiki you may use previous versions of the Extension.

To install the Jmol extension:

1. Download the latest release of Jmol (Jmol-16.xx.xx-binary.zip)
2. Extract into a temporary location the jsmol.zip file from the Jmol release.
3. Create a Jmol folder in the extensions folder of your MediaWiki installation.
4. Extract into this Jmol folder the following contents from the jsmol.zip file:
   • the JSmol.min.js file,
   • the JSmol.GLmol.min.js file,
   • the j2s, php and idioma folders.
5. If you want users to have the option of using the Java applet modality of Jmol:
   1. create a java subfolder inside the extensions/Jmol folder
   2. go back to the Jmol release zip file and extract from its applet folder all files which name starts with JmolAppletSigned0 (that's currently 23 files)
6. Download all the source files of the Jmol extension and place them in the extensions/Jmol folder.
7. Add the following line to your LocalSettings.php file (near the end):

<syntaxhighlight lang="php">

require_once("extensions/Jmol/Jmol.php"); </syntaxhighlight>

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
• Template:Ll

First, you need to authorize new file extensions being uploaded in the wiki, using Template:Ll.

For example, if you want to authorize uploading of CML files (*.cml), you can add the following line in your LocalSettings.php file: <syntaxhighlight lang="php"> $wgFileExtensions[] = 'cml'; </syntaxhighlight>

Suggestion for other molecular file types: <syntaxhighlight lang="php"> $wgFileExtensions[] = 'mol'; $wgFileExtensions[] = 'pdb'; $wgFileExtensions[] = 'xyz'; </syntaxhighlight>

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 Template:Ll 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: <syntaxhighlight lang="php"> $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' ) ); </syntaxhighlight>

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/libs/mime/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 mime.types:

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 text/plain

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

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

Note: This list is not complete.

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.

wgJmolAuthorizeJmolMolTag

Authorize the use of the <jmolMol> tag. Default is true.

wgJmolAuthorizeJmolSmilesTag

Authorize the use of the <jmolSmiles> tag. Default is true.

wgJmolPdbServer

specifies the server and url where pdb-formatted files will be retrieved from (to be used by the jmolPdb 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 Jmol.php file.

wgJmolMolServer

specifies the server and url where mol-formatted files will be retrieved from (to be used by the jmolMol 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 load $name 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.

Troubleshooting

Options in LocalSettings.php have no effect

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

Weblinks

• Jmol official Wiki
• Browse extension source code
• Special:Version at Proteopedia, a MediaWiki site dedicated to display of proteins and molecules, using the Jmol Extension.

[[Category:3D extensions{{#translation:}}]]

Contributors

AngelHerraez