Actions

Difference between revisions of "Plugins/Blocktype/Jmol"

From Mahara Wiki

< Plugins
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Jmol plugin ==
+
[[File:Jsmol.png]]
  
Mahara artefact file blocktype jmol plugin
+
== Jmol/JSmol plugin ==
  
This plugin provides an interactive 3D display of local chemical structure files using the Jmol applet
+
Mahara artefact file blocktype jmol/jsmol plugin
 +
 
 +
This plugin provides the interactive 3D display of chemical structure files, uploaded to Mahara, using Jmol/JSmol. JSmol is the recently developed JavaScript/HTML5 version of Jmol. JSmol offers wider platform support than the Jmol Java applet.
  
 
http://jmol.sourceforge.net
 
http://jmol.sourceforge.net
  
It is similar to other Mahara artefact file blocktype plugins, in particular the Embedded media plugin.
+
It is similar to other Mahara artefact file blocktype plugins such as the Embedded media plugin.
 
+
Jmol/JSmol can use a variety of chemical structure file formats (chemical MIME types).
The Jmol applet can use a variety of chemical structure file formats (chemical MIME types)
 
  
 
http://wiki.jmol.org/index.php/File_formats
 
http://wiki.jmol.org/index.php/File_formats
 
http://www.ch.ic.ac.uk/chemime/
 
http://www.ch.ic.ac.uk/chemime/
  
This plugin currently uses the following file types, though others can be easily added (see below)
+
This plugin currently uses the following subset of chemical structure file (chemical MIME) types, though others can be easily added (see below)
  
 
  alc  chemical/x-alchemy    Alchemy
 
  alc  chemical/x-alchemy    Alchemy
Line 24: Line 25:
 
  mol2 chemical/x-mol2        SYBYL Tripos Mol2 file format
 
  mol2 chemical/x-mol2        SYBYL Tripos Mol2 file format
 
  pdb  chemical/x-pdb        Protein Data Bank
 
  pdb  chemical/x-pdb        Protein Data Bank
 +
pdb.gz                      Gzipped Protein Data Bank
 +
pse  chemical/x-pse        PyMOL Session
 
  sdf  chemical/x-mdl-sdfile  Structure Data File
 
  sdf  chemical/x-mdl-sdfile  Structure Data File
 
  xyz  chemical/x-xyz        XYZ Coordinate Animation format
 
  xyz  chemical/x-xyz        XYZ Coordinate Animation format
Line 30: Line 33:
  
 
When editing the contents of a Mahara Page (View), drag the Jmol icon from the 'Files, images and videos' tab into your Page (View)
 
When editing the contents of a Mahara Page (View), drag the Jmol icon from the 'Files, images and videos' tab into your Page (View)
 +
 +
[[File:Thumb-jsmol.png]] For Mahara 1.6, and 1.7. New JSmol icon
 +
 +
[[File:Thumb-jmol.png]] For Mahara 1.5
 +
 +
[[File:thumb2.png]] For Mahara 1.2, 1.3 and 1.4
  
 
Then upload/select the appropriate file and set the appropriate applet width and height (default 300 px v 300 px)
 
Then upload/select the appropriate file and set the appropriate applet width and height (default 300 px v 300 px)
Line 46: Line 55:
  
  
The latest version of the plugin, for Mahara 1.2, 1.3 and 1.4, can be downloaded from Github
+
The latest version of the plugin, for Mahara 1.2, 1.3, 1.4, 1.5, 1.6 and 1.7 can be downloaded from Github
  
 
https://github.com/geoffrowland/mahara-artefact_file_blocktype_jmol
 
https://github.com/geoffrowland/mahara-artefact_file_blocktype_jmol
Line 53: Line 62:
  
 
Some other edits of Mahara files are required (or you can copy across the appropriate files from the download bundle).
 
Some other edits of Mahara files are required (or you can copy across the appropriate files from the download bundle).
 +
 +
If you wish to display binary format (.pse or .pdb.gz) files then you need to edit /lib/web.php to comment out the line that loads jQuery
 +
and load JSmoljQuery instead. The completed edit should be as follows:
 +
 +
// $javascript_array[] = $jsroot . 'jquery/jquery.js';
 +
$javascript_array[] = $wwwroot . 'artefact/file/blocktype/jmol/jsmol/js/JSmoljQuery.js';
  
 
To  
 
To  
Line 60: Line 75:
 
add, immediately after the other file types
 
add, immediately after the other file types
  
  // Chemical
+
  <nowiki>// Chemical</nowiki>
 
  $string['alc'] = 'Alchemy File';
 
  $string['alc'] = 'Alchemy File';
 
  $string['cif'] = 'Crystallographic Information File';
 
  $string['cif'] = 'Crystallographic Information File';
Line 69: Line 84:
 
  $string['mol2'] = 'SYBYL Tripos Mol2 File';
 
  $string['mol2'] = 'SYBYL Tripos Mol2 File';
 
  $string['pdb'] = 'Protein Data Bank';
 
  $string['pdb'] = 'Protein Data Bank';
 +
$string['pse'] = 'PyMOL Session';
 
  $string['sdf'] = 'MDL Structure Data File';
 
  $string['sdf'] = 'MDL Structure Data File';
 
  $string['xyz'] = 'XYZ Coordinate Animation Format';
 
  $string['xyz'] = 'XYZ Coordinate Animation Format';
  
To
 
  
/artefact/file/lib.php
+
Then you need to edit /artefact/file/lib.php to set the appropriate file mime-types. The precise details differ depending on the Mahara version
  
immediately after
+
For '''Mahara 1.6''': Immediately after
 +
 
 +
        if (empty($data->filetype) || $data->filetype == 'application/octet-stream') {
 +
            $data->filetype = $data->guess;
 +
        }
 +
add
 +
        <nowiki>// The browser may have been wrong, so use file extension to force some mime-types.////</nowiki>
 +
        $ext = $data->oldextension;
 +
        switch ($ext) {
 +
            case 'mm': $data->filetype = 'application/x-freemind';
 +
            break;
 +
            case 'alc': $data->filetype = 'chemical/x-alchemy';
 +
            break;
 +
            case 'cif': $data->filetype = 'chemical/x-cif';
 +
            break;
 +
            case 'cml': $data->filetype = 'chemical/x-cml';
 +
            break;
 +
            case 'hin': $data->filetype = 'chemical/x-hin';
 +
            break;
 +
            case 'mcif': $data->filetype = 'chemical/x-mmcif';
 +
            break;
 +
            case 'mol': $data->filetype = 'chemical/x-mdl-molfile';
 +
            break;
 +
            case 'mol2': $data->filetype = 'chemical/x-mol2';
 +
            break;
 +
            case 'pdb': $data->filetype = 'chemical/x-pdb';
 +
            break;
 +
            case 'pse': $data->filetype = 'chemical/x-pse';
 +
            break;
 +
            case 'sdf': $data->filetype = 'chemical/x-mdl-sdfile';
 +
            break;
 +
            case 'xyz': $data->filetype = 'chemical/x-xyz';
 +
            break;
 +
      }
 +
 
 +
For '''Mahara 1.4''': Immediately after
  
 
         if ($um->file['type'] == 'application/octet-stream') {
 
         if ($um->file['type'] == 'application/octet-stream') {
             // the browser wasn't sure, so use file_mime_type to guess
+
             <nowiki>// the browser wasn't sure, so use file_mime_type to guess</nowiki>
 
             require_once('file.php');
 
             require_once('file.php');
 
             $data->filetype = file_mime_type($um->file['tmp_name']);
 
             $data->filetype = file_mime_type($um->file['tmp_name']);
Line 87: Line 137:
 
         }
 
         }
 
add
 
add
         // The browser may have been wrong, so use file extension to force some mime-types.////
+
         <nowiki>// The browser may have been wrong, so use file extension to force some mime-types.////</nowiki>
 
         require_once('file.php');  
 
         require_once('file.php');  
 
         switch ($um->original_filename_extension()) {
 
         switch ($um->original_filename_extension()) {
Line 107: Line 157:
 
             break;
 
             break;
 
             case 'pdb': $data->filetype = 'chemical/x-pdb';
 
             case 'pdb': $data->filetype = 'chemical/x-pdb';
 +
            break;
 +
            case 'pse': $data->filetype = 'chemical/x-pse';
 
             break;
 
             break;
 
             case 'sdf': $data->filetype = 'chemical/x-mdl-sdfile';
 
             case 'sdf': $data->filetype = 'chemical/x-mdl-sdfile';
Line 120: Line 172:
 
just before  
 
just before  
  
     <!-- General types -->
+
     <nowiki><!-- General types --></nowiki>
  
 
add
 
add
  
     <!-- Chemical formats -->
+
     <nowiki><!-- Chemical formats --></nowiki>
 
     <filetype>
 
     <filetype>
 
         <description>alc</description>
 
         <description>alc</description>
Line 171: Line 223:
 
         <mimetypes>
 
         <mimetypes>
 
             <mimetype>chemical/x-pdb</mimetype>
 
             <mimetype>chemical/x-pdb</mimetype>
 +
        </mimetypes>
 +
    </filetype>
 +
    <filetype>
 +
        <description>pse</description>
 +
        <mimetypes>
 +
            <mimetype>chemical/x-pse</mimetype>
 
         </mimetypes>
 
         </mimetypes>
 
     </filetype>
 
     </filetype>
Line 194: Line 252:
  
  
You will have to edit /artefact/file/version.php to increase the value of $config->version (e.g. +1). Thin visit the administration interface to force the an update and load the chemical mimetypes into the Mahara database  
+
You will have to edit /artefact/file/version.php to increase the value of $config->version (e.g. +1). Then visit the administration interface to force the an update and load the chemical mimetypes into the Mahara database  
  
You also need to download and unpack the latest Jmol stable version (12.0.43 at the time of writing), rename the unpacked folder (e.g. /jmol-12.0.43) to /jmol and copy this (and its contents) into the /lib folder of your Mahara installation to give /lib/jmol. Not all the contents of the jmol folder are actually required. However, Jmol code is frequently updated so it is convenient to just replace the /jmol folder with the latest version. This folder is shared with the Jmol NIH plugin (if installed).
+
This plugin includes a recent Jmol/JSmol stable version (13.2.7) located in the /jsmol folder. However, JSmol code is frequently updated and you may wish to replace/update the contents of the /jsmol folder with the latest version, unpacked from http://chemapps.stolaf.edu/jmol/jsmol.zip.
  
----
+
Using JSmol alongsisde MathJax
'''NB Jmol versions 12.0.44 to 12.0.46 inclusive have issues with the plugin due to a bug in Jmol.js. So, use Jmol 12.0.43 (or earlier) or Jmol 12.0.47 (or later)'''
+
If you are using MathJax to display formulae in Mahara pages, for example as described in https://mahara.org/interaction/forum/topic.php?id=3759#post16560
----
+
then you may need to uncomment the following code from /artefact/file/blocktype/jmol/lib.php.
 +
 
 +
        //$html .= 'MathJax.Hub.Queue(function () {';
 +
        //$html .= 'loadJmol'.$id.'();';
 +
        //$html .= '});';
 +
        //$html .= 'loadJmol'.$id.' = function() {';
 +
        $html .= 'Jmol.setDocument(0);';
 +
        $html .= 'Jmol.getApplet("jmol'.$id.'", info'.$id.');';
 +
        $html .= 'jQuery("#jmoldiv'.$id.'").html(Jmol.getAppletHtml(jmol'.$id.'));';
 +
        $html .= 'jQuery("#controls'.$id.'").html('.$controls.')';
 +
        //$html .= '}';
 +
        $html .= '</script>';
 +
        return $html;
 +
 
 +
Finally, visit your Site Administration > Plugin Administration page to enable the plugin. Remember to select the chemical file types you wish to use from the configuration menu.
 +
 
 +
For the JSmol version, you need an HTML5-capable JavaScript-enabled browser. Recent versions of Firefox, Chrome, Safari, Opera and Internet Explorer 9 or 10 should work. IE 8 defaults to the Jmol Java Applet (you will need an up-to-date Java installation on the client computer. http://www.java.com).
 +
 
 +
During configuration and initial display of Jmol/JSmol embedded in a page, you may have to refresh the browser.
  
 
Remember to set appropriate server permissions for the new folders and contents.
 
Remember to set appropriate server permissions for the new folders and contents.
  
Finally, visit your Site Administration > Plugin Administration page to enable the plugin. Remember to select the chemical file types you wish to use from the configuration menu.  
+
This plugin includes a recent Jmol/JSmol version (13.3.3_dev) located in the /jsmol folder. However, JSmol code is frequently updated so you may wish to replace/update the contents of the /jsmol folder with the latest version, unpacked from http://chemapps.stolaf.edu/jmol/zip/jsmol.zip
 +
 
 +
Finally, visit your Site Administration > Plugin Administration page to enable the plugin. Remember to select the chemical file types you wish to use from the configuration menu '''file/jmol[config]'''.  
  
 
Of course, for the Jmol plugin, you will need an up-to-date Java installation on the client computer.  
 
Of course, for the Jmol plugin, you will need an up-to-date Java installation on the client computer.  
Line 228: Line 306:
 
*default controls for crystal display filling unit cell(s) (e.g. .cif files from AMS or COD)
 
*default controls for crystal display filling unit cell(s) (e.g. .cif files from AMS or COD)
  
*other? reaction animations? orbital display?
+
*other? reaction animations? orbital display? spectral display? virtual model kit?

Revision as of 00:39, 7 October 2013

Jsmol.png

Jmol/JSmol plugin

Mahara artefact file blocktype jmol/jsmol plugin

This plugin provides the interactive 3D display of chemical structure files, uploaded to Mahara, using Jmol/JSmol. JSmol is the recently developed JavaScript/HTML5 version of Jmol. JSmol offers wider platform support than the Jmol Java applet.

http://jmol.sourceforge.net

It is similar to other Mahara artefact file blocktype plugins such as the Embedded media plugin. Jmol/JSmol can use a variety of chemical structure file formats (chemical MIME types).

http://wiki.jmol.org/index.php/File_formats http://www.ch.ic.ac.uk/chemime/

This plugin currently uses the following subset of chemical structure file (chemical MIME) types, though others can be easily added (see below)

alc  chemical/x-alchemy     Alchemy
cif  chemical/x-cif         Crystallographic Information File
cml  chemical/x-cml         Chemical Markup Language
hin  chemical/x-hin         HyperChem Input file
mcif chemical/x-mmcif       MacroMolecular Crystallographic Information File
mol  chemical/x-mdl-molfile MDL Molfile
mol2 chemical/x-mol2        SYBYL Tripos Mol2 file format
pdb  chemical/x-pdb         Protein Data Bank
pdb.gz                      Gzipped Protein Data Bank
pse  chemical/x-pse         PyMOL Session
sdf  chemical/x-mdl-sdfile  Structure Data File
xyz  chemical/x-xyz         XYZ Coordinate Animation format

Use

When editing the contents of a Mahara Page (View), drag the Jmol icon from the 'Files, images and videos' tab into your Page (View)

Thumb-jsmol.png For Mahara 1.6, and 1.7. New JSmol icon

Thumb-jmol.png For Mahara 1.5

Thumb2.png For Mahara 1.2, 1.3 and 1.4

Then upload/select the appropriate file and set the appropriate applet width and height (default 300 px v 300 px)

For more advanced Jmol use, there are a couple of textarea controls that allow you to:

1. Specify an optional Jmol startup script to customise initial display of the applet http://chemapps.stolaf.edu/jmol/docs/

2. Enter optional Jmol.js JavaScript commands to add custom controls below the applet http://jmol.sourceforge.net/jslibrary/

Default script values are applied for general use.

NB Development has focused on functionality, and there may be security implications in running these scripts.

Installation

The latest version of the plugin, for Mahara 1.2, 1.3, 1.4, 1.5, 1.6 and 1.7 can be downloaded from Github

https://github.com/geoffrowland/mahara-artefact_file_blocktype_jmol

On unpacking, the /jmol folder (and its contents) is copied into the /artefact/file/blocktype folder of your Mahara installation.

Some other edits of Mahara files are required (or you can copy across the appropriate files from the download bundle).

If you wish to display binary format (.pse or .pdb.gz) files then you need to edit /lib/web.php to comment out the line that loads jQuery and load JSmoljQuery instead. The completed edit should be as follows:

// $javascript_array[] = $jsroot . 'jquery/jquery.js'; $javascript_array[] = $wwwroot . 'artefact/file/blocktype/jmol/jsmol/js/JSmoljQuery.js';

To

/artefact/file/lang/en.utf8/artefact.file.php

add, immediately after the other file types

// Chemical
$string['alc'] = 'Alchemy File';
$string['cif'] = 'Crystallographic Information File';
$string['cml'] = 'Chemical Markup language';
$string['hin'] = 'HyperChem Input File';
$string['mcif'] = 'MacroMolecular Crystallographic Information File';
$string['mol'] = 'MDL Molfile';
$string['mol2'] = 'SYBYL Tripos Mol2 File';
$string['pdb'] = 'Protein Data Bank';
$string['pse'] = 'PyMOL Session';
$string['sdf'] = 'MDL Structure Data File';
$string['xyz'] = 'XYZ Coordinate Animation Format';


Then you need to edit /artefact/file/lib.php to set the appropriate file mime-types. The precise details differ depending on the Mahara version

For Mahara 1.6: Immediately after

       if (empty($data->filetype) || $data->filetype == 'application/octet-stream') {
           $data->filetype = $data->guess;
       }

add

       // The browser may have been wrong, so use file extension to force some mime-types.////
       $ext = $data->oldextension;
       switch ($ext) {
           case 'mm': $data->filetype = 'application/x-freemind';
           break;
           case 'alc': $data->filetype = 'chemical/x-alchemy';
           break;
           case 'cif': $data->filetype = 'chemical/x-cif';
           break;
           case 'cml': $data->filetype = 'chemical/x-cml';
           break;
           case 'hin': $data->filetype = 'chemical/x-hin';
           break;
           case 'mcif': $data->filetype = 'chemical/x-mmcif';
           break;
           case 'mol': $data->filetype = 'chemical/x-mdl-molfile';
           break;
           case 'mol2': $data->filetype = 'chemical/x-mol2';
           break;
           case 'pdb': $data->filetype = 'chemical/x-pdb';
           break;
           case 'pse': $data->filetype = 'chemical/x-pse';
           break;
           case 'sdf': $data->filetype = 'chemical/x-mdl-sdfile';
           break;
           case 'xyz': $data->filetype = 'chemical/x-xyz';
           break;
      }

For Mahara 1.4: Immediately after

       if ($um->file['type'] == 'application/octet-stream') {
           // the browser wasn't sure, so use file_mime_type to guess
           require_once('file.php');
           $data->filetype = file_mime_type($um->file['tmp_name']);
       }
       else {
           $data->filetype = $um->file['type'];
       }

add

       // The browser may have been wrong, so use file extension to force some mime-types.////
       require_once('file.php'); 
       switch ($um->original_filename_extension()) {
           case 'mm': $data->filetype = 'application/x-freemind';
           break;
           case 'alc': $data->filetype = 'chemical/x-alchemy';
           break;
           case 'cif': $data->filetype = 'chemical/x-cif';
           break;
           case 'cml': $data->filetype = 'chemical/x-cml';
           break;
           case 'hin': $data->filetype = 'chemical/x-hin';
           break;
           case 'mcif': $data->filetype = 'chemical/x-mmcif';
           break;
           case 'mol': $data->filetype = 'chemical/x-mdl-molfile';
           break;
           case 'mol2': $data->filetype = 'chemical/x-mol2';
           break;
           case 'pdb': $data->filetype = 'chemical/x-pdb';
           break;
           case 'pse': $data->filetype = 'chemical/x-pse';
           break;
           case 'sdf': $data->filetype = 'chemical/x-mdl-sdfile';
           break;
           case 'xyz': $data->filetype = 'chemical/x-xyz';
           break;
       }

To

/artefact/file/filetypes.xml

just before

   <!-- General types -->

add

   <!-- Chemical formats -->
   <filetype>
       <description>alc</description>
       <mimetypes>
           <mimetype>chemical/x-alchemy</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>cif</description>
       <mimetypes>
           <mimetype>chemical/x-cif</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>cml</description>
       <mimetypes>
           <mimetype>chemical/x-cml</mimetype>
       </mimetypes>
   </filetype> 
   <filetype>
       <description>hin</description>
       <mimetypes>
           <mimetype>chemical/x-hin</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>mcif</description>
       <mimetypes>
           <mimetype>chemical/x-mmcif</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>mol</description>
       <mimetypes>
           <mimetype>chemical/x-mdl-molfile</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>mol2</description>
       <mimetypes>
           <mimetype>chemical/x-mol2</mimetype>
       </mimetypes>
   </filetype>              
   <filetype>
       <description>pdb</description>
       <mimetypes>
           <mimetype>chemical/x-pdb</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>pse</description>
       <mimetypes>
           <mimetype>chemical/x-pse</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>sdf</description>
       <mimetypes>
           <mimetype>chemical/x-mdl-sdfile</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>xyz</description>
       <mimetypes>
           <mimetype>chemical/x-xyz</mimetype>
       </mimetypes>
   </filetype>
   <filetype>
       <description>mm</description>
       <mimetypes>
           <mimetype>application/x-freemind</mimetype>
       </mimetypes>
   </filetype>


You will have to edit /artefact/file/version.php to increase the value of $config->version (e.g. +1). Then visit the administration interface to force the an update and load the chemical mimetypes into the Mahara database

This plugin includes a recent Jmol/JSmol stable version (13.2.7) located in the /jsmol folder. However, JSmol code is frequently updated and you may wish to replace/update the contents of the /jsmol folder with the latest version, unpacked from http://chemapps.stolaf.edu/jmol/jsmol.zip.

Using JSmol alongsisde MathJax If you are using MathJax to display formulae in Mahara pages, for example as described in https://mahara.org/interaction/forum/topic.php?id=3759#post16560 then you may need to uncomment the following code from /artefact/file/blocktype/jmol/lib.php.

       //$html .= 'MathJax.Hub.Queue(function () {';
       //$html .= 'loadJmol'.$id.'();';
       //$html .= '});';
       //$html .= 'loadJmol'.$id.' = function() {';
       $html .= 'Jmol.setDocument(0);';
       $html .= 'Jmol.getApplet("jmol'.$id.'", info'.$id.');';
       $html .= 'jQuery("#jmoldiv'.$id.'").html(Jmol.getAppletHtml(jmol'.$id.'));';
       $html .= 'jQuery("#controls'.$id.'").html('.$controls.')';
       //$html .= '}';
       $html .= '</script>';
       return $html;

Finally, visit your Site Administration > Plugin Administration page to enable the plugin. Remember to select the chemical file types you wish to use from the configuration menu.

For the JSmol version, you need an HTML5-capable JavaScript-enabled browser. Recent versions of Firefox, Chrome, Safari, Opera and Internet Explorer 9 or 10 should work. IE 8 defaults to the Jmol Java Applet (you will need an up-to-date Java installation on the client computer. http://www.java.com).

During configuration and initial display of Jmol/JSmol embedded in a page, you may have to refresh the browser.

Remember to set appropriate server permissions for the new folders and contents.

This plugin includes a recent Jmol/JSmol version (13.3.3_dev) located in the /jsmol folder. However, JSmol code is frequently updated so you may wish to replace/update the contents of the /jsmol folder with the latest version, unpacked from http://chemapps.stolaf.edu/jmol/zip/jsmol.zip

Finally, visit your Site Administration > Plugin Administration page to enable the plugin. Remember to select the chemical file types you wish to use from the configuration menu file/jmol[config].

Of course, for the Jmol plugin, you will need an up-to-date Java installation on the client computer.

http://www.java.com

During configuration and initial display of the Jmol applet in a view, you may have to refresh the browser to see the applet embedded in the Page (View)

See Also

Jmol NIH Plugin

Chem 2D NIH Plugin

To Do

Currently, the plugin adds a default set of controls appropriate for basic organic chemistry

Add option buttons to the file-picker/edit interface for:

  • default controls for biological macromolecules (e.g. .pdb files from PDB)
  • default controls for crystal display filling unit cell(s) (e.g. .cif files from AMS or COD)
  • other? reaction animations? orbital display? spectral display? virtual model kit?