MediaWiki/Installation

Installation of the Jmol (JSmol) Extension for Mediawiki

Admin All this must be done by the wiki administrator.

The files forming the Jmol Extension are part of the Jmol source code and may hence be retrieved from the SVN system.

arrangement of folders and files of the 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. It is not compatible either with newest versions of MediaWiki. There is work in progress for a v.6 of the extension to be compatible with MediaWIki 1.41

To install the Jmol extension using Jmol 14

1. Download the release of Jmol (Jmol-14.xx.xx-binary.zip) You need version 14.29.32 or later.
2. Extract into a temporary location the jsmol.zip file from the Jmol release.
3. Create a Jmol subfolder in the extensions folder of your MediaWiki installation.
4. Extract (upload) 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 (the latter one may not exist in latest Jmol versions).

To install the Jmol extension using Jmol 16

1. Download the latest release of Jmol (Jmol-16.xx.xx-binary.zip) Good compatibility may be expected, but the Extension has not been tested yet against Jmol 16.
2. Extract into a temporary location the jsmol.zip file from the Jmol release.
3. Create a Jmol subfolder in the extensions folder of your MediaWiki installation.
4. Extract (upload) into this Jmol folder the following contents from the jsmol.zip file (all located inside a jsmol subfolder):
   • the JSmol.min.js file,
   • the JSmol.GLmol.min.js file,
   • the j2s and php folders. Note: if the latter folder contains a jsmol2.php file, rename it to jsmol.php before uploading.
   • the idioma folder, if present (at least until version 16.1.39); this is used to support language localization.

Further steps

1. Download all the source files of the Jmol extension and place them in the extensions/Jmol folder.
2. Add the following line to your LocalSettings.php file (near the end): require_once("extensions/Jmol/Jmol.php");
3. Optional change of settings:

You can configure the Jmol extension with several settings added after the require_once line (default value underlined):

• $wgJmolAuthorizeJmolTag = true / false : Authorize the use of the <jmol/> tag.
• $wgJmolAuthorizeJmolFileTag = true / false : Authorize the use of the <jmolFile/> tag.
• $wgJmolAuthorizeJmolPdbTag = true / false : Authorize the use of the <jmolPdb/> tag.
• $wgJmolAuthorizeJmolSmilesTag = true / false : Authorize the use of the <jmolSmiles/> tag.
• $wgJmolAuthorizeUploadedFile = true / false : Authorize the use of <uploadedFileContents>.
• $wgJmolAuthorizeUrl = true / false : Authorize the use of <urlContents>.
• $wgJmolDefaultAppletSize = 400 : Size in pixels of the JSmol panel.
• $wgJmolDefaultScript = ... : Default script.
• $wgJmolExtensionPath = "extensions/Jmol" : Path to the directory where the Jmol extension is installed. This must be an absolute path, therefore if you customize it, make sure it is prepended with $wgScriptPath (see example in Jmol.php).
• $wgJmolForceNameSpace = ... : Force the NameSpace where JSmol will go looking for wiki pages containing molecular data (using <wikiPageContents>).
• $wgJmolShowWarnings = true / false : Display warnings when users try to use disabled features.
• Deprecated:
  • $wgJmolUsingSignedAppletByDefault = true / false : Choose if the signed Jmol applet will be used by default. Note: the signed Jmol applet is signed with a default certificate. If you want to use the signed Jmol applet in your wiki, I suggest resigning the Jmol applet with your own certificate.
  • $wgJmolAuthorizeChoosingSignedApplet = true / false : Authorize users to choose between the unsigned and the signed Jmol applet.

Managing molecular structure files

Authorizing uploads

Web server PHP setup

The configuration of your web server needs to allow uploads by users (a global setting, not just for the wiki). Find a line with file_uploads in the php.ini file and change it to file_uploads = on. Going to the Special:Upload page in your wiki will tell you if uploads are enabled or not.

Wiki upload setup

If you want to authorize users to upload files containing molecular data (for using the <uploadedFileContents> subtag), you need to do the following:

By default, MediaWiki authorizes the uploading of a very limited set of file types, based on file extensions and MIME types (see Configuring_file_uploads ). By default, uploading molecular files is not authorized, so the configuration must be modified to take advantage of all the Jmol extension features. You can check what file extensions are authorized in the Special:Upload page.

First, you need to authorize new file extensions being uploaded in the wiki, using $wgFileExtensions . For example, add one or several of the following lines at the end of your LocalSettings.php file:

$wgFileExtensions[] = 'pdb';
$wgFileExtensions[] = 'mol';
$wgFileExtensions[] = 'xyz';
$wgFileExtensions[] = 'cml';

Configuring recognition of molecular files

By default, the MIME type detection of MediaWiki (read 'additional help' below) only detects some molecular files as basic MIME types (text/plain, application/xml, …).

Recent versions of MediwWiki (e.g. 1.41) already include by default recognition of MIME type of .pdb, .xyz and .mol files (as well as other MDL-MOLfile formats like 'sdf', 'rxn', 'rd' and 'rg' extensions). However, there is still a mismatch with the detected MIME type that prevents the upload, so it may need to be fixed:

Near the end of your LocalSettings.php file, add these lines:

$wgHooks['MimeMagicImproveFromExtension'][] = static function ( $mimeAnalyzer, $ext, &$mime ) {
  if     ( $ext == 'mol' ) { $mime = 'chemical/x-mdl-molfile'; }
  elseif ( $ext == 'sdf' ) { $mime = 'chemical/x-mdl-sdfile'; }
  elseif ( $ext == 'xyz' ) { $mime = 'chemical/x-xyz'; }
  elseif ( $ext == 'pdb' ) { $mime = 'chemical/x-pdb'; }
  elseif ( $ext == 'cml' ) { $mime = 'chemical/x-cml'; }
};

For molecular file formats based on XML (like CML files *.cml), it is commonly needed to enhance the MIME type detection using $wgXMLMimeTypes , which allows the mapping between the root element of the file and the MIME type. For example, add the following lines near the end of 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' ) );

The following, alternative or complementary, solution seems not to be necessary in recent MW versions:

By default, MediaWiki checks that the file extension matches the MIME type that has been detected. For this, MediaWiki uses includes/libs/mime/MimeMap.php in MediaWiki installation. In former MW versions, the file is includes/mime.types.

File extensions for molecular models are probably missing from this file by default, so you need to modify it. For example, *.cml might 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/libs/mime/MimeMap.php or includes/mime.types:

application/xml xml xsl xsd cml
chemical/x-cml cml

(check for location of several instances of chemical/x-mdl-molfile to find where and how to add this extra definition) or use the LocalSettings.php method described above.

Additional help

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:

• Configuring_file_uploads
• Mime_type_detection
• Image administration

File icons

Now that uploading new file extensions has been authorized, you can do a final modification so that molecular files are shown with a specific icon in categories (see examples in Category:XYZ_file).

You can add an icon in the skins/common/images/icons folder for each extension of molecular files (such as fileicon-cml.png).

Installation of older versions

Version 4 of the Jmol Extension is compatible with MediaWiki 1.16; installation instructions.

The Jmol Extension below version 3.3 uses another extension, Stub Manager, so you first need to install it.

Deprecated

Installation of the Jmol extension was described on the Jmol extension page on MediaWiki.

That page has been removed since the Jmol Extension is not compatible with recent versions of MediaWiki.

See also

How to use the Extension

Contributors

AngelHerraez