User:AngelHerraez/Sandbox MW Extension

From Jmol
< User:AngelHerraez
Revision as of 17:29, 16 January 2025 by AngelHerraez (talk | contribs) (Created page with "{{Extension |status = unstable |type1 = tag |hook1 = ParserFirstCallInit |author = NicoV, Jaime Prilusky,...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Template:Extension

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

Documentation and full details on its installation and use, including demonstration examples, can be found on the Jmol Wiki.

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 file that has been previously uploaded into a Wiki. Some examples of its usage are available in the Extension page of the Jmol Wiki[1]. This tag is only available if authorized in the configuration ($wgJmolAuthorizeJmolFileTag set to true which is the default configuration).

A few examples:

  • <source lang=html inline>Chair.cml</source> 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.
  • <source lang=html inline>Chair</source> 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.

<jmolSmiles>

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 Extension page of the Jmol Wiki[2] This tag is only available if authorized in the configuration ($wgJmolAuthorizeJmolSmilesTag set to true which is the default configuration).

A few examples:

  • <source lang=html inline>CCCNC</source> 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.
  • <source lang=html inline>Smiles</source> 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.

<jmolPdb>

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 Extension page of the Jmol Wiki[3] This tag is only available if authorized in the configuration ($wgJmolAuthorizeJmolPdbTag set to true which is the default configuration).

A few examples:

  • <source lang=html inline>1ALE</source> 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.
  • <source lang=html inline>Show 1ALE</source> 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.

<jmol>

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 Extension page of the Jmol Wiki[4] This tag is only available if authorized in the configuration ($wgJmolAuthorizeJmolTag set to true which is the default configuration).

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:

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

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

  1. ↑ https://wiki.jmol.org/index.php/MediaWiki/Extension
  2. ↑ https://wiki.jmol.org/index.php/MediaWiki/Extension
  3. ↑ https://wiki.jmol.org/index.php/MediaWiki/Extension
  4. ↑ https://wiki.jmol.org/index.php/MediaWiki/Extension

Contributors

AngelHerraez

Retrieved from "https://wiki.jmol.org/index.php?title=User:AngelHerraez/Sandbox_MW_Extension&oldid=10347"