Skip to content
Allows display of 3D interactive chemical structures using JSmol/Jmol in the Mahara ePortfolio. Use the master branch for the latest versions (1.6,1.7 and 1.8) of Mahara
JavaScript Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
artefact/file
README

README

-----------
Jmol plugin
-----------

Mahara artefact file blocktype jmol plugin.

This plugin provides an interactive 3D display of local chemical structure files using the Jmol applet.

Has now been updated to default to JSmol, the JavaScript/HTML version of Jmol.

It is similar to other Mahara artefact file blocktype plugins, in particular the Embedded media plugin.

The Jmol/JSmol applet can use a variety of chemical structure file formats (mime-types)

This plugin currently uses the following file types

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
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)

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

For more advanced Jmol users, 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

Note that development has focused on the functionality of this, and there may be security implications of running these scripts. Happy to receive advice and guidance from Mahara security gurus about this.

------------
Installation
------------

The latest version of the plugin, for Mahara 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8 and 1.9 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).

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.9, 1.8, 1.7 and 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>
    <!-- FreeMind -->
    <filetype>
        <description>mm</description>
        <mimetypes>
            <mimetype>application/x-freemind</mimetype>
        </mimetypes>
    </filetype>

Then, to install the file types with the Mahara database, you will need to increment (e.g. increase by 1) the value of $config->version in /artefact/file/version.php

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

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;

This results in JSmol rendering after MathJax equations have displayed and prevents 'Math Processing Errors' due to conflicts between MathJax and JSmol.

This plugin includes a recent Jmol/JSmol stable version (14.0) 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. 

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.

You can’t perform that action at this time.