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 6 of the Jmol Extension has been tested against MediaWiki 1.39-1.43. There are significant changes in MediaWiki, so this procedure will not work with older versions.

Installation

1. In the extensions folder of your wiki, create a Jmol folder.
2. Download all the source files of the Jmol extension (version 6.x) and place them in the extensions/Jmol folder.
3. Download the latest release of Jmol (Jmol-16.xx.xx-binary.zip)
   • Extract into a temporary location the jsmol.zip file from the Jmol release.
   • Open this file and extract the following contents (all located inside a jsmol subfolder):
     • the JSmol.min.js file,
     • the JSmol.GLmol.min.js file,
     • the j2s and php folders.
     • (JmolData.jar and JSmol.GLmol.min.nojq.js, shown in the figure, are not essential)
4. Upload the above files and folders to the extensions/Jmol/JSmol folder.
5. Edit LocalSettings.php adding a line wfLoadExtension('Jmol');

The utility copyJSmolForJmolExtension.php is included as a convenient way to facilitate direct extraction of the needed files from Jmol-16.xx.xx-binary.zip (steps 3 and 4 below). It is used like this:

copyJSmolForJmolExtension.php Jmol-xx.xx.xx-binary.zip /mediawiki/extensions/Jmol

Further steps

Optional change of settings:

You can configure the Jmol extension with several settings, usually added at the end of LocalSettings.php, and in any case after the wfLoadExtension('Jmol'); (default value underlined):

• $wgJmolAuthorizeJmolFileTag = true / false : Authorize the use of the <jmolFile/> tag.
• $wgJmolAuthorizeJmolMolTag = true / false : Authorize the use of the <jmolMol/> tag.
• $wgJmolAuthorizeJmolPdbTag = true / false : Authorize the use of the <jmolPdb/> tag.
• $wgJmolAuthorizeJmolSmilesTag = true / false : Authorize the use of the <jmolSmiles/> tag.
• $wgJmolAuthorizeJmolTag = true / false : Authorize the use of the <jmol/> tag.
• $wgJmolAuthorizeUploadedFile = true / false : Authorize the use of <uploadedFileContents>.
• $wgJmolAuthorizeUrl = true / false : Authorize the use of <urlContents>.
• $wgJmolDefaultScript = ... : Default script.
• $wgJmolDefaultAppletSize = 400 : Size in pixels of the JSmol panel.
• $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.

Additional settings:

• $wgJmolDefaultAppletColor
• $wgJmolMaxAppletSize
• $wgJmolDefaultRenderingEngine = HTML5 / WebGL
• $wgJmolMolServer
• $wgJmolPdbServer
• $wgJmolPlatformSpeed
• $wgJmolDefaultCaptionCSS (used in Proteopedia)
• $wgJmolDefaultTitleCSS

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';

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

Configuring recognition of molecular files

By default, MediaWiki checks that the file extension matches the MIME type that has been detected. Such MIME type detection may or not recognize properly the not-so-common extensions you might want to use. On the other hand, it is important to not allow arbitrary kinds of file being uploaded to MediaWiki.

I you find trouble, you may try reading MW documentation about recognition of MIME types as well as some settings that used to be able to fix this in former versions of the Extension (with no warranties for this v6 and MW 1.43 to behave in the same way)

Also, this setting may be relevant:

• $wgVerifyMimeType = false

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 5 of the Jmol Extension is compatible with MediaWiki 1.32; installation instructions.

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.

Extension documented in MediaWiki

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

That page has been removed since the Jmol Extension (up to v5) was not compatible with recent versions of MediaWiki. We are planning to restore that page soon pointing to the information here.

See also

How to use the Extension

Contributors

AngelHerraez