About JSmol2wp

This Wordpress plugin is based on the JSmol molecular graphics viewer from Bob Hanson, Zhou Renjian, and Takanori Nakane. Adaptation of JSmol to a Wordpress plugin was started by Jim Hu in June 2014. JSmol2wp should be considered beta!!! Use at your own risk and please report problems.

This is a shortcode extension. Use

[jsmol pdb='accession']

for a minimal version showing macromolecule structures from the PDB.

Installation

Warning: JSmol2wp alters the allowed MIME types for uploaded files to include chemical/pdb, whether or not you ever use the shortcode!!. Installation is typical for Wordpress plugins not yet in the Wordpress ecosystem.

Obtain the zip archive from github.
From plugins control, click Add new
Select upload and upload the zip file
Activate it.

Usage

Loading a structure

Proteins remotely from the pdb

[jsmol pdb='accession']

is equivalent to

[jsmol acc='accession' type='pdb']

Small molecules remotely from NCI and from PubChem

Figure 1. Screenshot of JSmol2wp viewer for a small molecule

Jmol can look up small molecules by name at the NCI resolver (http://cactus.nci.nih.gov/chemical/structure). Use

[jsmol acc = $name]

where name is a molecule name. For example, acc='$tryptophan' loads the tryptophan structure (Figure 1).

Alternatively, you can use the NCBI PubChem server with:

[jsmol acc = :name]

From files uploaded to your media library

JSmol2wp can also work with files that are uploaded to your media library. JSmol2wp modifies your Wordpress installation to allow additional mime types to be uploaded. The following have been added so far:

.pdb = 'chemical/x-pdb'
.cif' = 'chemical/x-cif'
.cml = 'chemical/x-cml+xml'
.jvxi = 'chemical/x-jvxi'
.mol = 'chemical/x-mdl-molfile'
.mol2 = 'chemical/x-mol2'
.xyz = 'chemical/x-xyz'
.ccp4 = 'text/ccp4'

If you use acc=accession and type=extension; JSmol2wp uses these to find the matching filename among the Wordpress uploaded media files. JSmol2wp will look to see if a file has been uploaded to your wordpress and it will use that file if it can find it. Example

[jsmol acc='caffeine' type='mol']

Will look for an uploaded file named caffeine.mol. If it can't find a matching post for an uploaded attachment and type=pdb, it will try http://rcsb.org/pdb. If it can't find a match there either, you'll get an error message in the JSmol window.

telling JSmol2wp where to look for a data file

Alternatively, you can point JSmol2wp to a file path that is not in your media library. You can use

fileurl='http://path_to_file'

to force JSmol2wp to use that file. You can use any file with a publicly accessible URL

Add a caption

The captions parameter adds a text caption above the applet viewer.

Commands and buttons

JSmol2wp will always put a set of standard buttons below your viewer. It will try to guess which set of buttons to use, depending on whether you are loading a protein or a small molecule. This is determined by type (pdb or anything else)

The commands parameter allows you to run additional Jmol commands on loading or create buttons that will run commands. Separate commands with three pipes ( '|||")

Commands syntax

Individual ommands have the format label=script, where label is the text you want on the button, and script is the Jmol script you want to run.JSmol2wp parses these, first by splitting on the ||| string and then on the = character. There are three kinds of command pairs.

JSmol2wp creates a button with the label. Clicking the button runs the script, unless:
If the label is blank, JSmol2wp runs the script immediately. Use this to override the initialization on a per applet basis
If the label is jmolCommandInput JSmol2wp appends a command input box at the bottom.

Debugging problems

add debug=value where the value can be:

short: just shows
- the applet id
- the accession
- the type
full: dumps the jsmol2wp object and runs other tests.

Additional parameters

Figure 2. Screenshot of JSmol2wp viewer for a with an isosurface loaded from a local file

JSmol2wp can take additional optional parameters:

acc: accession. Use as an alternative to pdb=, and use this for accessions that are not pdb files.
type: the type of viewer. Default = pdb. JSmol will try to guess what you want for the default view.
wrap: the number of buttons to put in each row. default = 4
id: use this to distinguish multiple copies of the shortcode if needed
isosurface: filename of an uploaded file, or a URL for an isosurface.
load: override the how JSmol does its loading with your own Jmol commands.
debug: show information about paths to required js files. default = false

Figure 2 shows a structure and isosurface loaded from files uploaded to a local directory outside the Wordpress uploads path. The markup is:

[jsmol acc='isosurface_example' 
caption="Isosurface test from Henry Rzepa" 
fileurl='http://localhost/tmp/s_den.cub_.xyz' 
isosurface='http://localhost/tmp/s_den.cub_.jvxl']

Note that in this example, the acc parameter isn't really an accession. It's only being used to create a text label in the applet viewer.

Examples

Basic

[jsmol pdb='1LMB' caption='lambda repressor headpiece']

Advanced

Figure 2. Screenshot of JSmol2wp viewer for a protein, with custom command/script execution buttons

Figure 3 is a screenshot of the sample viewer in this example post here. The markup for the lambda repressor example in that post is:

[jsmol pdb='1LMB' caption='&lambda; repressor headpiece' 
commands='
arm = select 1-6:3, 1-6:4;color yellow;|||
helix-turn-helix = select 33-52:3, 33-52:4; color yellow; hide hoh;|||
helix 5 = select *:3,*:4; spacefill off; cartoon; select 84,87; color yellow;
spacefill on; select *;
hide hoh; hide *:1,*:2;
#moveto 2 0 1 0 0 0 0;
zoomto (84:4) 300;|||
DNA only =
display all;
hide protein;|||
Protein only =
hide all;
display protein;|||
DNA interaction =
hide all;
display 33-52:3, 33-52:4, 1-6:3, 1-6:4, *:1, *:2;
cartoon only;
select 40-52:4;
spacefill 23%;
wireframe 0.15;
color cpk;
zoomto (45:4) 300;
']

This creates six custom buttons based on the text from the shortcode, and a reset button that tries to restore the original view. A lot of the suboptimal behavior of those buttons is from my lack of mastery of Jmol scripting. Note that Jmol commands can be used to load command sets from files.

Known issues

Some themes will add HTML tags inside the scripting stanzas created by JSmol2wp. This can cause the plugin to fail. You can detect this by viewing source in your favorite browser. Please let me know what theme caused the problem, and if it's a free one Ican do some testing to see if we can overcome the problem.
HTML entities to make symbols in the captions can behave oddly if you edit the post with the visual editor.
Accessions can't have spaces.

Please report bugs

at GitHub or send a tweet to @jimhu

License

JSmol2wp is available under the GPL-3.0 license this document updated by Jim Hu on June 23, 2014