Difference between revisions of "User:AngelHerraez/Sandbox MW Extension"

From Jmol
Jump to navigation Jump to search
(Created page with "{{Extension |status = unstable |type1 = tag |hook1 = ParserFirstCallInit |author = NicoV, Jaime Prilusky,...")
 
(this is draft for content that will go in /www.mediawiki.org/wiki/Extension:Jmol)
 
(One intermediate revision by the same user not shown)
Line 34: Line 34:
 
The '''Jmol''' extension allows for displaying molecular models in interactive 3D inside wiki pages using [[:en:Jmol|JSmol HTML5 objects]].
 
The '''Jmol''' extension allows for displaying molecular models in interactive 3D inside wiki pages using [[:en:Jmol|JSmol HTML5 objects]].
  
−
Documentation and full details on its installation and use, including demonstration examples, can be found on the [https://wiki.jmol.org/index.php/MediaWiki Jmol Wiki].
+
Documentation on its installation and use can be found at [https://sf.net/p/jmol/wiki/MW%20Extension/ the Jmol project pages], as well as at [https://wiki.jmol.org/index.php/MediaWiki Jmol Wiki], with full details and demonstration examples.
  
 
== Usage ==
 
== 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:
 
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 a popup window, upon user action
 
* in-line, inserted in the page as the page is loaded
 
* in-line, inserted in the page as the page is loaded
 
* in-line, inserted in the page upon user action
 
* in-line, inserted in the page upon user action
−
* in a popup window, upon user action
 
  
 
=== {{tag|jmolFile|open}} ===
 
=== {{tag|jmolFile|open}} ===
  
−
The {{tag|jmolFile|open}} 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<ref>https://wiki.jmol.org/index.php/MediaWiki/Extension </ref>.
+
The {{tag|jmolFile|open}} tag can be used to display in 3D a molecule or structure file that has been previously uploaded into a Wiki.  
−
This tag is only available if authorized in the configuration (<code>$wgJmolAuthorizeJmolFileTag</code> set to <code>true</code> which is the default configuration).
+
:This tag may be disabled by administrators in the configuration file of the wiki, using <code>$wgJmolAuthorizeJmolFileTag = false</code>
  
 
A few examples:
 
A few examples:
−
* <source lang=html inline><jmolFile>Chair.cml</jmolFile></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 <code>File:Chair.cml</code>.
+
* <source lang=html inline><jmolFile>Chair.cml</jmolFile></source> will put in the article a ''Chair.cml'' link. When users click on it, a popup window will display the 3D structure specified in <code>File:Chair.cml</code>.
−
* <source lang=html inline><jmolFile text="Chair">Chair.cml</jmolFile></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 <code>File:Chair.cml</code>.
+
* <source lang=html inline><jmolFile text="chair conformation">Chair.cml</jmolFile></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 <code>File:Chair.cml</code>.
−
 
 
−
The following attributes are available for the {{tag|jmolFile|open}} tag:
 
−
* '''text''': To configure the text used for the link. By default, the file name is used for the link.
 
  
 
=== {{tag|jmolSmiles|open}} ===
 
=== {{tag|jmolSmiles|open}} ===
  
−
The {{tag|jmolSmiles|open}} tag can be used to display in 3d a molecule file using its [[:en:SMILES|SMILES]] notation. Some examples of its usage are available in the Extension page of the Jmol Wiki<ref>https://wiki.jmol.org/index.php/MediaWiki/Extension </ref>
+
The {{tag|jmolSmiles|open}} tag can be used to display in 3D a molecule file using its [[:en:SMILES|SMILES]] notation.  
−
This tag is only available if authorized in the configuration (<code>$wgJmolAuthorizeJmolSmilesTag</code> set to <code>true</code> which is the default configuration).
+
:This tag may be disabled by administrators in the configuration file of the wiki, using <code>$wgJmolAuthorizeJmolSmilesTag = false</code>
  
 
A few examples:
 
A few examples:
−
* <source lang=html inline><jmolSmiles>CCCNC</jmolSmiles></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><jmolSmiles>CCCNC</jmolSmiles></source> will put in the article a ''CCCNC'' link. When users click on it, a popup window will display the 3D structure that matches the SMILES string ''CCCNC''.
−
* <source lang=html inline><jmolSmiles text="Smiles">CCCNC</jmolSmiles></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''.
+
* <source lang=html inline><jmolSmiles text="smiles notation">CCCNC</jmolSmiles></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''.
−
 
 
−
The following attributes are available for the {{tag|jmolSmiles|open}} tag:
 
−
* '''text''': To configure the text used for the link. By default, the SMILES string is used for the link.
 
  
 
=== {{tag|jmolPdb|open}} ===
 
=== {{tag|jmolPdb|open}} ===
  
−
The {{tag|jmolPdb|open}} tag can be used to display in 3d a molecule file using its [[:en:Protein Data Bank|PDB]] code. Some examples of its usage are available in the Extension page of the Jmol Wiki<ref>https://wiki.jmol.org/index.php/MediaWiki/Extension </ref>
+
The {{tag|jmolPdb|open}} tag can be used to display in 3D a molecule file using its [[:en:Protein Data Bank|PDB]] code.
−
This tag is only available if authorized in the configuration (<code>$wgJmolAuthorizeJmolPdbTag</code> set to <code>true</code> which is the default configuration).
+
:This tag may be disabled by administrators in the configuration file of the wiki, using <code>$wgJmolAuthorizeJmolPdbTag = false</code>
  
 
A few examples:
 
A few examples:
−
* <source lang=html inline><jmolPdb>1ALE</jmolPdb></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><jmolPdb>1ALE</jmolPdb></source> will put in the article a ''1ALE'' link. When users click on it, a popup window will display the 3D structure matching the PDB code ''1ALE''.
−
* <source lang=html inline><jmolPdb text="Show 1ALE">1ALE</jmolPdb></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''.
+
* <source lang=html inline><jmolPdb text="Partial structure of Apo-C-I">1ALE</jmolPdb></source> will put in the article a ''Partial structure of Apo-C-I'' link. When this link is clicked on, a popup window will display the 3D structure matching the PDB code ''1ALE''.
  
−
The following attributes are available for the {{tag|jmolPdb|open}} tag:
+
=== {{tag|jmol|open}} ===
−
* '''text''': To configure the text used for the link. By default, the PDB code is used for the link.
 
  
−
=== {{tag|jmol|open}} ===
+
The {{tag|jmol|open}} 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 [https://sf.net/p/jmol/wiki/MW%20Extension/ the Jmol project pages] or in [http://wiki.jmol.org/index.php/MediaWiki/Extension the Extension page at the Jmol Wiki].
 +
:This tag may be disabled by administrators in the configuration file of the wiki, using <code>$wgJmolAuthorizeJmolTag = false</code>
  
−
The {{tag|jmol|open}} 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<ref>https://wiki.jmol.org/index.php/MediaWiki/Extension </ref>
 
−
This tag is only available if authorized in the configuration (<code>$wgJmolAuthorizeJmolTag</code> set to <code>true</code> which is the default configuration).
 
  
 
== Installing Jmol extension ==
 
== Installing Jmol extension ==
−
[[File:Jmol Extension 6 folders setup.jpg|frame|right|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.
 
'''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:
+
To install the Jmol extension in your wiki, follow instructions at [https://sf.net/p/jmol/wiki/MW%20Extension/ the Jmol project pages]
−
# 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 <code>jsmol.zip</code> file from the Jmol release.
 
−
# Create a <code>Jmol</code> folder in the <code>extensions</code> folder of your MediaWiki installation.
 
−
# Extract into this <code>Jmol</code> folder the following contents from the <code>jsmol.zip</code> file:
 
−
#* the <code>JSmol.min.js</code> file,
 
−
#* the <code>JSmol.GLmol.min.js</code> file,
 
−
#* the <code>j2s</code>, <code>php</code> and <code>idioma</code> folders.
 
−
# If you want users to have the option of using the Java applet modality of Jmol:
 
−
## create a <code>java</code> subfolder inside the <code>extensions/Jmol</code> folder
 
−
## go back to the Jmol release <code>zip</code> file and extract from its <code>applet</code> folder all files which name starts with <code>JmolAppletSigned0</code> (that's currently 23 files)
 
−
# 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 [[Manual:LocalSettings.php|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 [[Manual:Configuring_file_uploads|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]]
 
−
* {{ll|Manual:Image administration}}
 
−
 
 
−
First, you need to authorize new file extensions being uploaded in the wiki, using {{ll|Manual:$wgFileExtensions|$wgFileExtensions}}.
 
−
 
 
−
For example, if you want to authorize uploading of [[:en:Chemical Markup Language|CML files]] (<code>*.cml</code>), 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 [[Manual:Mime type detection|MIME type detection]] configuration of MediaWiki only detects molecular files as basic  MIME types (<code>text/plain</code>, <code>application/xml</code>, …). 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 {{ll|Manual:$wgXMLMimeTypes|$wgXMLMimeTypes}} which allows the mapping between the root element of the file and the MIME type.
 
−
 
 
−
For example, for enhancing detection for [[:en:Chemical Markup Language|CML files]] (<code>*.cml</code>), 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 <code>includes/libs/mime/mime.types</code> 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, <code>*.cml</code> can be detected as <code>chemical/x-cml</code> or <code>application/xml</code> (depending on your [[Manual:Mime type detection|MIME type detection]] configuration), so you need to make the following additions to <code>mime.types</code>:
 
−
application/xml xml xsl xsd '''cml'''
 
−
'''chemical/x-cml cml'''
 
−
 
 
−
Suggestion for other molecular file types (taken from [https://www.ch.ic.ac.uk/chemime/ The Chemical MIME Home Page]):
 
−
<pre>
 
−
chemical/x-xyz xyz
 
−
chemical/x-mdl-molfile mol
 
−
chemical/x-pdb pdb
 
−
</pre>
 
−
Alternativley, all 3 might be added to MIME type <code>text/plain</code>
 
−
 
 
−
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 [http://wiki.jmol.org/index.php/Category:XYZ_file Jmol Wiki]).
 
−
You can add an icon in the <code>skins/common/images/icons</code> folder for each extension for molecular files (for example <code>fileicon-cml.png</code>).
 
−
You can use [http://wiki.jmol.org/index.php/File:Fileicon_Chemical.png this file].
 
−
 
 
−
=== Configuration ===
 
−
 
 
−
There are some options you can specify in your [[LocalSettings.php]] file (after the <code>require_once</code> line you've already added):
 
−
 
 
−
''Note: This list is not complete.''
 
−
 
 
−
; wgJmolAuthorizeJmolTag
 
−
: Authorize the use of the {{tag|jmol|single}} tag. Default is <code>true</code>.
 
−
; wgJmolAuthorizeJmolFileTag
 
−
: Authorize the use of the {{tag|jmolFile|single}} tag. Default is <code>true</code>.
 
−
; wgJmolAuthorizeJmolPdbTag
 
−
: Authorize the use of the {{tag|jmolPdb|single}} tag. Default is <code>true</code>.
 
−
; wgJmolAuthorizeJmolMolTag
 
−
: Authorize the use of the {{tag|jmolMol|single}} tag. Default is <code>true</code>.
 
−
; wgJmolAuthorizeJmolSmilesTag
 
−
: Authorize the use of the {{tag|jmolSmiles|single}} tag. Default is <code>true</code>.
 
−
; wgJmolPdbServer
 
−
: specifies the server and url where pdb-formatted files will be retrieved from (to be used by the <code>jmolPdb</code> tag). The url must include <code>####</code> 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 <code>Jmol.php</code> file.
 
−
; wgJmolMolServer
 
−
: specifies the server and url where mol-formatted files will be retrieved from (to be used by the <code>jmolMol</code> tag). The url must include <code>####</code> 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 <code>load $name</code> which is internally converted to the proper url by Jmol/Jsmol)
 
  
 
== Wikis using the Jmol extension ==
 
== Wikis using the Jmol extension ==
  
−
If you know a wiki using the Jmol extension, please add it to the list of [http://wiki.jmol.org/index.php/Wikis_Using_Jmol Wikis using Jmol].
+
If you know a wiki using the Jmol extension, please add it to the list of [http://wiki.jmol.org/index.php/Wikis_Using_Jmol Wikis using Jmol] or report it at [https://sf.net/p/jmol/mailman/jmol-users/ the Jmol-users e-mail list].
  
 
== Troubleshooting ==
 
== Troubleshooting ==
  
−
=== Options in LocalSettings.php have no effect ===
+
Please address any queries to [https://sf.net/p/jmol/mailman/jmol-developers/ the Jmol-developers e-mail list]
  
−
* Make sure you specify the options ''after'' including the extension.
 
  
 
== Weblinks ==
 
== Weblinks ==
  
−
<!--* [http://www.jmol.org Jmol official web site]-->
+
* [http://jmol.sf.net Jmol official web site]
−
* [https://wiki.jmol.org Jmol official Wiki]
+
* [http://wiki.jmol.org Jmol official Wiki]
−
* [https://sourceforge.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ Browse extension source code]
+
* [https://sf.net/p/jmol/ Jmol project site]
 +
* [https://sf.net/p/jmol/code/HEAD/tree/trunk/Jmol-extensions/wiki/MediaWiki/ Browse extension source code]
 
* [https://proteopedia.org/wiki/index.php/Special:Version Special:Version at Proteopedia], a MediaWiki site dedicated to display of proteins and molecules, using the Jmol Extension.
 
* [https://proteopedia.org/wiki/index.php/Special:Version Special:Version at Proteopedia], a MediaWiki site dedicated to display of proteins and molecules, using the Jmol Extension.
  
 
[[Category:3D extensions{{#translation:}}]]
 
[[Category:3D extensions{{#translation:}}]]

Latest revision as of 20:37, 21 January 2025

Template: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 a popup window, upon user action
  • in-line, inserted in the page as the page is loaded
  • in-line, inserted in the page 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, using $wgJmolAuthorizeJmolFileTag = false

A few examples:

  • <source lang=html inline>Chair.cml</source> will put in the article a Chair.cml link. When users click on it, 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, using $wgJmolAuthorizeJmolSmilesTag = false

A few examples:

  • <source lang=html inline>CCCNC</source> will put in the article a CCCNC link. When users click on it, 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, using $wgJmolAuthorizeJmolPdbTag = false

A few examples:

  • <source lang=html inline>1ALE</source> will put in the article a 1ALE link. When users click on it, a popup window will display the 3D structure matching the PDB code 1ALE.
  • <source lang=html inline>Partial structure of Apo-C-I</source> will put in the article a Partial structure of Apo-C-I 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, using $wgJmolAuthorizeJmolTag = false


Installing 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 in your wiki, follow instructions at the Jmol project pages

Wikis using the Jmol extension

If you know a wiki using the Jmol extension, please add it to the list of Wikis using Jmol or report it at the Jmol-users e-mail list.

Troubleshooting

Please address any queries to the Jmol-developers e-mail list


Weblinks

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

Contributors

AngelHerraez

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