MediaWiki/Installation - Revision history

AngelHerraez: /* Installation */

2025-01-17T15:49:28Z

‎Installation

AngelHerraez: AngelHerraez moved page MediaWiki/Installation/v6 to MediaWiki/Installation without leaving a redirect: doc for v5 has been archive and this is the update for v6 as default doc

2025-01-15T17:46:47Z

AngelHerraez moved page MediaWiki/Installation/v6 to MediaWiki/Installation without leaving a redirect: doc for v5 has been archive and this is the update for v6 as default doc

AngelHerraez: copyJSmolForJmolExtension and other documentation

2025-01-15T17:43:27Z

copyJSmolForJmolExtension and other documentation

AngelHerraez: documenting v6 of the Extension

2025-01-12T19:34:24Z

documenting v6 of the Extension

AngelHerraez: typo

2025-01-06T18:45:43Z

typo

AngelHerraez: adapting to document version 6 of the Extension

2025-01-05T19:36:50Z

adapting to document version 6 of the Extension

AngelHerraez: adapting to document version 6 of the Extension

2025-01-05T19:25:52Z

adapting to document version 6 of the Extension

AngelHerraez: adapting to document version 6 of the Extension

2025-01-05T19:00:45Z

adapting to document version 6 of the Extension

New page

= 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 [{{SVN Trunk}}Jmol-extensions/wiki/MediaWiki/ the SVN system].

[[File:Jmol_Extension_5_folders_setup_3.png|frame|right|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 ==
# Download the [https://sourceforge.net/projects/jmol/files/Jmol/Version%2014.32/ release] of [[:en:Jmol|Jmol]] (<code>Jmol-14.xx.xx-binary.zip</code>) You need version 14.29.32 or later.
# Extract into a temporary location the {{file|jsmol.zip}} file from the Jmol release.
# Create a {{folder|Jmol}} subfolder in the {{folder|extensions}} folder of your MediaWiki installation.
# Extract (upload) into this {{folder|Jmol}} folder the following contents from the {{file|jsmol.zip}} file:
#* the {{file|JSmol.min.js}} file,
#* the {{file|JSmol.GLmol.min.js}} file,
#* the {{folder|j2s}}, {{folder|php}} and {{folder|idioma}} folders ''(the latter one may not exist in latest Jmol versions)''.

== To install the Jmol extension using Jmol 16 ==
# Download the [https://sourceforge.net/projects/jmol/files/Jmol/ latest release] of [[:en:Jmol|Jmol]] (<code>Jmol-16.xx.xx-binary.zip</code>) Good compatibility may be expected, but the Extension has not been tested yet against Jmol 16.
# Extract into a temporary location the {{file|jsmol.zip}} file from the Jmol release.
# Create a {{folder|Jmol}} subfolder in the {{folder|extensions}} folder of your MediaWiki installation.
# Extract (upload) into this {{folder|Jmol}} folder the following contents from the {{file|jsmol.zip}} file (all located inside a {{folder|jsmol}} subfolder):
#* the {{file|JSmol.min.js}} file,
#* the {{file|JSmol.GLmol.min.js}} file,
#* the {{folder|j2s}} and {{folder|php}} folders. ''Note:'' if the latter folder contains a {{file|jsmol2.php}} file, rename it to {{file|jsmol.php}} before uploading.
#* the {{folder|idioma}} folder, if present (at least until version 16.1.39); this is used to support language localization.

== Further steps ==

# Download all the [http://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ source files of the Jmol extension] and place them in the <code>extensions/Jmol</code> folder.
# Add the following line to your [https://www.mediawiki.org/wiki/Manual:LocalSettings.php LocalSettings.php file] (near the end): <code>require_once("extensions/Jmol/Jmol.php");</code>
# Optional change of settings:
You can configure the Jmol extension with several settings added after the <code>require_once</code> line (default value underlined):
* <tt>$wgJmolAuthorizeJmolTag = true / false</tt> : Authorize the use of the {{Tag|jmol/}} tag.
* <tt>$wgJmolAuthorizeJmolFileTag = true / false</tt> : Authorize the use of the {{Tag|jmolFile/}} tag.
* <tt>$wgJmolAuthorizeJmolPdbTag = true / false</tt> : Authorize the use of the {{Tag|jmolPdb/}} tag.
* <tt>$wgJmolAuthorizeJmolSmilesTag = true / false</tt> : Authorize the use of the {{Tag|jmolSmiles/}} tag.
* <tt>$wgJmolAuthorizeUploadedFile = true / false</tt> : Authorize the use of {{Tag|uploadedFileContents}}.
* <tt>$wgJmolAuthorizeUrl = true / false</tt> : Authorize the use of {{Tag|urlContents}}.
* <tt>$wgJmolDefaultAppletSize = 400</tt> : Size in pixels of the JSmol panel.
* <tt>$wgJmolDefaultScript = ...</tt> : Default script.
* <tt>$wgJmolExtensionPath = "extensions/Jmol"</tt> : 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 <tt>$wgScriptPath</tt> (see example in Jmol.php).
* <tt>$wgJmolForceNameSpace = ...</tt> : Force the NameSpace where JSmol will go looking for wiki pages containing molecular data (using {{Tag|wikiPageContents}}).
* <tt>$wgJmolShowWarnings = true / false</tt> : Display warnings when users try to use disabled features.
* Deprecated:
** <tt>$wgJmolUsingSignedAppletByDefault = true / false</tt> : 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.''
** <tt>$wgJmolAuthorizeChoosingSignedApplet = true / false</tt> : 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 <code>file_uploads</code> in the {{file|php.ini}} file and change it to <code>file_uploads = on</code>.
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 {{Tag|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 {{MWmanual|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 {{MWmanual|$wgFileExtensions}}.
For example, add one or several of the following lines at the end of your {{file|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 (<code>text/plain</code>, <code>application/xml</code>, …).

Recent versions of MediwWiki (e.g. 1.41) already include by default recognition of MIME type of {{file|.pdb}}, {{file|.xyz}} and {{file|.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 {{file|LocalSettings.php}} file, add these lines:
<pre>$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'; }
};
</pre>

For molecular file formats based on XML (like [[:en:Chemical Markup Language|CML files]] {{File|*.cml}}), it is commonly needed to enhance the MIME type detection using {{MWmanual|$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 {{file|LocalSettings.php}} file:
<pre>$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' ) );
</pre>

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 {{file|includes/libs/mime/MimeMap.php}} in MediaWiki installation. In former MW versions, the file is {{file|includes/mime.types}}.

File extensions for molecular models are probably missing from this file by default, so you need to modify it.
For example, {{file|*.cml}} might be detected as <code>chemical/x-cml</code> or <code>application/xml</code> (depending on your {{MWmanual|Mime_type_detection|MIME type detection}} configuration), so you need to make the following additions to {{file|includes/libs/mime/MimeMap.php}} or {{file|includes/mime.types}}:
application/xml xml xsl xsd '''cml'''
'''chemical/x-cml cml'''
(check for location of several instances of <code>chemical/x-mdl-molfile</code> to find where and how to add this extra definition) or use the {{file|LocalSettings.php}} method described above.

=== Additional help ===
<blockquote>
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:
* {{MWmanual|Configuring_file_uploads}}
* {{MWmanual|Mime_type_detection}}
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Image_administration Image administration]
</blockquote>

=== File icons ===
[[File:Fileicon_Chemical.png|50px|right|Example icon]]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 {{folder|skins/common/images/icons}} folder for each extension of molecular files (such as {{file|fileicon-cml.png}}).

== Installation of older versions ==
'''Version 4''' of the Jmol Extension is compatible with MediaWiki 1.16; [https://www.mediawiki.org/w/index.php?title=Extension:Jmol&oldid=2497254 installation instructions].

The Jmol Extension below '''version 3.3''' uses another extension, [[mw:Extension:StubManager|Stub Manager]], so you first need to install it.

== Deprecated ==
Installation of the Jmol extension was described on [[:mw:Extension:Jmol#Installing Jmol Extension|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 =
[[MediaWiki/Extension|How to use the Extension]]

@@ Line 10: / Line 10: @@
 == Installation ==
 # Download all the [http://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ source files of the Jmol extension] (version 6.x) and place them in the {{folder|extensions/Jmol}} folder.
 # Download the [https://sourceforge.net/projects/jmol/files/Jmol/ latest release] of Jmol (<code>Jmol-16.xx.xx-binary.zip</code>)
@@ Line 21: / Line 22: @@
 # Edit {{file|LocalSettings.php}} adding a line <code>wfLoadExtension('Jmol');</code>
-The utility {{file|copyJSmolForJmolExtension.php}} is included as a convenient way to facilitate direct extraction of the needed files from <code>Jmol-16.xx.xx-binary.zip</code> (steps 2 and 3 above).
+The utility {{file|copyJSmolForJmolExtension.php}} is included as a convenient way to facilitate direct extraction of the needed files from <code>Jmol-16.xx.xx-binary.zip</code> (steps 3 and 4 below).
-Usage:
+It is used like this:
- copyJSmolForJmolExtension.php Jmol-xx.xx.xx-binary.zip /mediawiki/extensions/Jmol
+:<code>copyJSmolForJmolExtension.php Jmol-xx.xx.xx-binary.zip /mediawiki/extensions/Jmol</code>
 == Further steps ==

@@ Line 21: / Line 21: @@
 # Edit {{file|LocalSettings.php}} adding a line <code>wfLoadExtension('Jmol');</code>
+The utility {{file|copyJSmolForJmolExtension.php}} is included as a convenient way to facilitate direct extraction of the needed files from <code>Jmol-16.xx.xx-binary.zip</code> (steps 2 and 3 above).
-:<span style="color:white;font-weight:bold;background:#8F6600;padding:0 1ex;">Warning: Everything below this was written for v5 and still needs verification for v6.
+Usage:
-</span>
+ 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 added after the <code>require_once</code> line (default value <u>underlined</u>):
+You can configure the Jmol extension with several settings, usually added at the end of {{file|LocalSettings.php}}, and in any case after the
-* <tt>$wgJmolAuthorizeJmolTag = <u>true</u> / false</tt> : Authorize the use of the  {{Tag|jmol/}} tag.
+<code>wfLoadExtension('Jmol');</code>
 * <tt>$wgJmolAuthorizeJmolFileTag = <u>true</u> / false</tt> : Authorize the use of the  {{Tag|jmolFile/}} tag.
 * <tt>$wgJmolAuthorizeJmolPdbTag = <u>true</u> / false</tt> : Authorize the use of the  {{Tag|jmolPdb/}} tag.
 * <tt>$wgJmolAuthorizeJmolSmilesTag = <u>true</u> / false</tt> : Authorize the use of the {{Tag|jmolSmiles/}} tag.
 * <tt>$wgJmolAuthorizeUploadedFile = true / <u>false</u></tt> : Authorize the use of {{Tag|uploadedFileContents}}.
 * <tt>$wgJmolAuthorizeUrl = true / <u>false</u></tt> : Authorize the use of {{Tag|urlContents}}.
 * <tt>$wgJmolDefaultAppletSize = <u>400</u></tt> : Size in pixels of the JSmol panel.
 * <tt>$wgJmolForceNameSpace = ...</tt> : Force the NameSpace where JSmol will go looking for wiki pages containing molecular data (using {{Tag|wikiPageContents}}).
 * <tt>$wgJmolShowWarnings = <u>true</u> / false</tt> : Display warnings when users try to use disabled features.
-* Deprecated:
-** <tt>$wgJmolUsingSignedAppletByDefault = true / <u>false</u></tt> : 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.''
+Additional settings:
-** <tt>$wgJmolAuthorizeChoosingSignedApplet = true / <u>false</u></tt> : Authorize users to choose between the unsigned and the signed Jmol applet.
+* <tt>$wgJmolDefaultAppletColor</tt>
 == Managing molecular structure files ==
@@ Line 63: / Line 73: @@
   $wgFileExtensions[] = 'cml';
 <blockquote>
 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:
@@ Line 107: / Line 79: @@
 * [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Image_administration Image administration]
 </blockquote>
 === File icons ===
@@ Line 113: / Line 95: @@
 == Installation of older versions ==
-'''Version 5''' of the Jmol Extension is compatible with MediaWiki 1.32; [[MediaWiki/ExtensionV5|installation instructions]].
+'''Version 5''' of the Jmol Extension is compatible with MediaWiki 1.32; [[MediaWiki/ExtensionV5#How_to_install_the_Jmol_Extension|installation instructions]].
 '''Version 4''' of the Jmol Extension is compatible with MediaWiki 1.16; [https://www.mediawiki.org/w/index.php?title=Extension:Jmol&oldid=2497254 installation instructions].
@@ Line 119: / Line 101: @@
 The Jmol Extension below '''version 3.3''' uses another extension, [[mw:Extension:StubManager|Stub Manager]], so you first need to install it.
-== Deprecated ==
+== Extension documented in MediaWiki ==
 Installation of the Jmol extension was described on [[:mw:Extension:Jmol#Installing Jmol Extension|the Jmol extension page on MediaWiki]].
-That page has been removed since the Jmol Extension is not compatible with recent versions of MediaWiki.
+That page has been removed since the Jmol Extension (up to v5) was not compatible with recent versions of MediaWiki.
 = See also =
 [[MediaWiki/Extension|How to use the Extension]]

@@ Line 8: / Line 8: @@
 '''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.
-== One-step installation ==
+== Installation ==
 # Download all the [http://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ source files of the Jmol extension] (version 6.x) and place them in the {{folder|extensions/Jmol}} folder.
 # Edit {{file|LocalSettings.php}} adding a line <code>wfLoadExtension('Jmol');</code>
-# Download the [https://sourceforge.net/projects/jmol/files/Jmol/ latest release] of [[:en:Jmol|Jmol]] (<code>Jmol-16.xx.xx-binary.zip</code>)
+:<span style="color:white;font-weight:bold;background:#8F6600;padding:0 1ex;">Warning: Everything below this was written for v5 and still needs verification for v6.
-# Extract into a temporary location the {{file|jsmol.zip}} file from the Jmol release.
+</span>
 == Further steps ==

@@ Line 111: / Line 111: @@
 == Installation of older versions ==
-'''Version 5''' of the Jmol Extension is compatible with MediaWiki 1.32; [[MediaWiki/ExtensionV5|installation instructions].
+'''Version 5''' of the Jmol Extension is compatible with MediaWiki 1.32; [[MediaWiki/ExtensionV5|installation instructions]].
 '''Version 4''' of the Jmol Extension is compatible with MediaWiki 1.16; [https://www.mediawiki.org/w/index.php?title=Extension:Jmol&oldid=2497254 installation instructions].

@@ Line 10: / Line 10: @@
 == One-step installation ==
-# Download all the [http://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ source files of the Jmol extension] (version 6.x) and place them in the <code>extensions/Jmol</code> folder.
+# Download all the [http://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ source files of the Jmol extension] (version 6.x) and place them in the {{folder|extensions/Jmol}} folder.
-# Edit {{file|LocalSettings.php}} adding a line <code>wfLoadExtension( 'Jmol' );</code
+# Edit {{file|LocalSettings.php}} adding a line <code>wfLoadExtension('Jmol');</code>
 == Alternative: update the installation with a newer JSmol version ==
@@ Line 22: / Line 22: @@
 #* the {{file|JSmol.GLmol.min.js}} file,
 #* the {{folder|j2s}} and {{folder|php}} folders.
 == Further steps ==
 You can configure the Jmol extension with several settings added after the <code>require_once</code> line (default value <u>underlined</u>):
 * <tt>$wgJmolAuthorizeJmolTag = <u>true</u> / false</tt> : Authorize the use of the  {{Tag|jmol/}} tag.
@@ Line 113: / Line 111: @@
 == Installation of older versions ==
 '''Version 4''' of the Jmol Extension is compatible with MediaWiki 1.16; [https://www.mediawiki.org/w/index.php?title=Extension:Jmol&oldid=2497254 installation instructions].

← Older revision	Revision as of 17:46, 15 January 2025
(No difference)

@@ Line 5: / Line 5: @@
 The files forming the Jmol Extension are part of the Jmol source code and may hence be retrieved from [{{SVN Trunk}}Jmol-extensions/wiki/MediaWiki/ the SVN system].
-[[File:Jmol_Extension_5_folders_setup_3.png|frame|right|arrangement of folders and files of the Jmol Extension]]
+[[File:Jmol_Extension_6_folders_setup.png|frame|right|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.
+'''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.
-== To install the Jmol extension using Jmol 14 ==
+== One-step installation ==
-# Download the [https://sourceforge.net/projects/jmol/files/Jmol/Version%2014.32/ release] of [[:en:Jmol|Jmol]] (<code>Jmol-14.xx.xx-binary.zip</code>) You need version 14.29.32 or later.
-# Extract into a temporary location the {{file|jsmol.zip}} file from the Jmol release.
+# Download all the [http://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ source files of the Jmol extension] (version 6.x) and place them in the <code>extensions/Jmol</code> folder.
-# Create a {{folder|Jmol}} subfolder in the {{folder|extensions}} folder of your MediaWiki installation.
+# Edit {{file|LocalSettings.php}} adding a line <code>wfLoadExtension( 'Jmol' );</code
-# Extract (upload) into this {{folder|Jmol}} folder the following contents from the {{file|jsmol.zip}} file:
-#* the {{file|JSmol.min.js}} file,
+== Alternative: update the installation with a newer JSmol version ==
-== To install the Jmol extension using Jmol 16 ==
+# Download the [https://sourceforge.net/projects/jmol/files/Jmol/ latest release] of [[:en:Jmol|Jmol]] (<code>Jmol-16.xx.xx-binary.zip</code>)
 # Extract into a temporary location the {{file|jsmol.zip}} file from the Jmol release.
-# Create a {{folder|Jmol}} subfolder in the {{folder|extensions}} folder of your MediaWiki installation.
+# Locate the {{folder|Jmol}} subfolder in the {{folder|extensions}} folder of your MediaWiki installation.
 # Extract (upload) into this {{folder|Jmol}} folder the following contents from the {{file|jsmol.zip}} file (all located inside a {{folder|jsmol}} subfolder):
 #* the {{file|JSmol.min.js}} file,
 #* the {{file|JSmol.GLmol.min.js}} file,
-#* the {{folder|j2s}} and {{folder|php}} folders. ''Note:'' if the latter folder contains a {{file|jsmol2.php}} file, rename it to {{file|jsmol.php}} before uploading.
+#* the {{folder|j2s}} and {{folder|php}} folders.
-#* the {{folder|idioma}} folder, if present (at least until version 16.1.39); this is used to support language localization.
 == Further steps ==
 # Add the following line to your [https://www.mediawiki.org/wiki/Manual:LocalSettings.php LocalSettings.php file] (near the end): <code>require_once("extensions/Jmol/Jmol.php");</code>
 # Optional change of settings: