Methods for setting up Jmol/JSmol web pages
- Jmol is a versatile system with very many abilities and modes of use. I am
a self-taught academic user who has found out how to use a small part of it, but I
do not claim any expertise other than what is presented here
- These web pages are intended to present my recipes for using Jmol to
colleagues who, like myself, are chemists rather than experienced web programmers
- I have no doubt that there are neater and possibly better ways of doing things
Editing web pages
- My web site, provided by Newcastle University, is mounted in
such a way that I can edit the requisite files directly from a Linux login
- In fact, I use the old program
Programmers File Editor running in a securely networked PC. This still works, even
in 64-bit Windows, and can edit files in Unix format as well as in DOS format.
It works as you would expect a simple Windows-based application to do,
can open multiple file windows to facilitate copy and paste, and avoids
having to learn to use one of the standard Linux editors, if one has not already done so
- I do not use a dedicated web page editor: it is not much effort to type in the
relatively small set of html tags and JavaScript constructs which I use (see below for
references to online reference manuals)
Languages required
HTML
- Web pages are written in HTML (HyperText Markup Language), which consist of plain
text to be delivered, between tags enclosed in angle brackets < > which tell the
browser what to do with the text
- A good introduction may be found at
https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML
- Once you get going, you can look up tag definitions at
https://developer.mozilla.org/en-US/docs/Web/HTML/Element
- You may want to use symbols such as ± or <, or Greek letters,
in your text. Such symbols are all available by using a
code which starts with a & sign and ends with a ;.
A particularly useful thing for separating
text, since the browser will reduce all multiple ordinary spaces to one space, is
the non-break space, which is invoked using the code Old-fashioned people
may use this for putting double spaces between sentences to improve legibility.
You can look up these codes at
https://www.w3schools.com/charsets/
In particular, the Greek letters are at
https://www.w3schools.com/charsets/ref_utf_greek.asp
The common symbols have an entry under 'Entity' in the tables: you just use
that in your code
- I make completely no claims for good web style, but you may learn a bit by
displaying the page source of a simple web page like this one, to see how tags and
charset codes are used. In Internet Explorer, click on Page, View source
or use the right mouse button menu. IE has the advantage over Chrome of colour
coding of all the non-text content
- I use HTML forms to allow the user to select a model and a method of presenting it,
before starting a Jmol applet to show the model. An introduction to using
HTML forms may be found at
https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms
JavaScript
- This is the computer language in which Jmol scripts, to control the Jmol applet,
are written
- JavaScript is a browser-side language: you embed the code in your HTML script
between <script type="text/javascript"> and </script> tags,
and consequently the user may see your programming
by using 'View source' in their browser
- Different parts of a JavaScript programme may appear at different points in your
HTML script, e.g. variable or function definitions in one script and variable use or
function calls in another: the browser adds them together as if they were a single script.
This makes it easier to use a script for several different models, customising
only part of it as required
- An introduction to JavaScript, along with sections on syntax, grammar etc. is at
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide
- If you want your models to appear in popup windows (so that the user may compare
them with each other) you will need to know about built-in properties of the browser
window: see
https://www.w3schools.com/jsref/obj_window.asp
PHP
- This is a server-side language which is commonly implemented in web servers. The
PHP Hypertext Preprocessor is a programme, running in the server,
which can receive the choices made by the
user in HTML forms and deliver HTML and JavaScript client-side code customised
according to those choices. It is controlled by PHP code in a .php file
which also contains the HTML and JavaScript code to be delivered
- For example, the HTML and JavaScript script in a .php file
can show a page with a Jmol model on
it, but PHP code in this script can set a variable to specify which of several such
models is to be loaded from its file and displayed
- The PHP code is acted upon in the server and is not sent to the browser, so the
user cannot see it: they just see the parts of the HTML and JavaScript code
selected by the PHP code to be sent
- PHP code is inserted within HMTL scripts in a .php file,
between the tag ends <?php and
?> and can be a little bit of code putting in the value of a variable at that point,
or several lines of code selecting whole sections of HTML or JavaScript to be sent or not to be
sent to the browser
- As with JavaScript, PHP variables defined in one part of the script are available
if you go back into PHP mode later in the script
- The briefest introduction to PHP is at
http://php.net/manual/en/intro-whatis.php
- The reference manual is at
http://php.net/manual/en/langref.php
Obtaining and installing Jmol
- Jmol may be downloaded from
https://sourceforge.net/projects/jmol/files/Jmol/
- I download it to my Windows PC and unzip it as far as producing a folder called
jmol–version where version is the version number, e.g. 14.15.2
- From that folder, I upload to my Linux web pages directory the files jsmol.zip
and Jmol.jar
- In Linux (using Windows Remote Desktop Connection) I unzip jsmol.zip (using the
command unzip rather than gunzip). This produces a directory called jsmol, with all
of the correct permissions for itself and all of the files in it.
I rename this as JmolFolder
- In JmolFolder I move all files from its java subdirectory to JmolFolder itself,
and destroy the java subdirectory
- I move Jmol.jar into JmolFolder and permit Jmol.jar read to group
and others
- In my Linux own commands directory, which is in my cshell path, I have a command
called jmol which contains
#!/bin/csh
java -jar path/JmolFolder/Jmol.jar
where path is the Linux path to my webpages directory where I have put JmolFolder
- To test the stand-alone Jmol application, I cd to a directory where I have
some model files, e.g. as .xyz coordinate files or as .mol files, and give the command
jmol &
A File menu lets me select a model, and mouse right click on the structure
allows me to open a console window into which I can type Jmol commands.
Exit from the Jmol application is by using the File menu, rather than by giving
a command from its console window
Jmol commands
- The main reference document for Jmol commands, to be used in the console of
the Jmol application or of the Jmol_S or JSmol web applets, or in scripts supplied to
them, is at
https://chemapps.stolaf.edu/jmol/docs/
This is a very large document in which commands and their parameters are described
very briefly. Quite a lot of this is directed at representing
biological molecules, and the relatively few examples tend to be from such chemistry.
People with a knowledge of Rasmol or Chime scripts will recognise many of the
most important commands, as Rasmol scripts are readable by Jmol with very little
alteration
-
A good demonstration web page illustrating the effect of many Jmol commands,
including those for Rasmol-like display of biological molecules, is at
http://earth.callutheran.edu/Academic_Programs/Departments/BioDev/omm/jsmolnew/scripting/molmast.htm
- My first command to the Jmol application tends to be
background white
which saves a lot of ink if one wants to print from the screen
- The most common operations on a model can be done using commands from the menu
obtained by mouse right click on the model, avoiding the need to open the console and
know the commands to type
- Much can be learnt by looking at the page source of working JSmol web pages
(see below)
Setting up the JSmol or Jmol_S applet on a web page
- This is described at
http://wiki.jmol.org/index.php/Jmol_JavaScript_Object
- The essential steps of this are best seen in the context of an example:
the following link will open in a separate window:
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/muchiral/showjmol.php?use=HTML5&filestem=b1df
- Now view the page source for this by mouse right click below the line of text
which is below the three buttons, and selecting View source. (If you right click
above this, you will get the Jmol menu instead of the browser menu)
- The first essential is a one-line JavaScript call which reads the JavaScript from
JSmol.min.js which is in JmolFolder. This creates a Jmol object as a property of
the browser window. As JavaScript knows now that Jmol is a property of window,
its methods etc. can simply be referred to in JavaScript as Jmol.method
e.g. Jmol.getApplet
- Next, a JavaScript structure called Info is set up, which contains information on
the mode to be used ('use') and where to find the components needed by the Jmol applet
- This is described quite readably at
http://wiki.jmol.org/index.php/Jmol_JavaScript_Object/Info
- Next, the applet itself is created with a call to Jmol.getApplet in which it is
sent the address of the Info structure, so that it knows what is required.
The call returns a value for the JavaScript variable JmolApplet0, which is used to
refer to the applet in all subsequent calls to Jmol functions,
so that the model, buttons, etc. will all belong to it
- Now we are ready to tell the applet to load the model. We send it
some Jmol commands in a call to Jmol.script
These are just a literal string of commands separated by semicolons, the last one
of which is a load command
- Notice that in this we come out of the quotes to add in the value of the
JavaScript variable filestem which has been set up just before the applet was created
and specifies which model we want, then the quotes are resumed to finish the string
- What is loaded is a .spt file, which contains a sequence of Chime/Rasmol commands
which are also valid in Jmol. These first of all load the atomic coordinates
from a correspondingly named .xyz file, then set the colour and size of the balls and
sticks, how different elements are to be represented, and the initial orientation,
found by trial and error using the Jmol standalone application, to best convey the
intended information about the molecule to the viewer
- You may see this in a separate window at:
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/b1df.spt.html
- Having a different .spt file for each model means that orientation etc. may be
tweaked to suit each one individually
- Jmol.script is one of several functions provided for interactions with the applet.
They are documented at
http://wiki.jmol.org/index.php/Jmol_JavaScript_Object/Functions
- The other function used in this example is Jmol.jmolButton which gives the
three buttons which allow the user to choose different styles or to reload the
initial one. Note that these are Jmol buttons, which operate directly on the
model as it is currently presented in the browser. This is as opposed
to HTML form buttons,
which (as I use them, for maximum compatibility), send information back to the server.
These will be discussed below
Using PHP to customise the script to show a Jmol model
- In the example, above, of a script to show a Jmol model
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/muchiral/showjmol.php?use=HTML5&filestem=b1df
you may notice that the web address ends in a query string. This contains
values for the use and filestem parameters, and will normally be sent by another
web page containing a HTML form in which the user will select them
(see below)
- The file pointed to is a .php file and the PHP Hypertext Preprocessor acts on
PHP code in the file to obtain the parameters from the query string and use them to
customise the JavaScript which is to be sent
- Because PHP code is acted upon in the server and not sent to the browser, it cannot
be seen when you view the page source. To work round this for the present document,
I have converted a copy of showjmol.php into HTML by changing all of
the special characters, such as angle brackets, to their &...; character set codes,
so that the preprocessor and the browser will show them rather than acting upon them
- You may see this in a separate window:
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/showjmol.php.html
- The <?php tag after the first comment starts a section of PHP code which ends
at the ?> tag before the first line of the HTML code to be delivered
- The first PHP action is to set a value for the PHP variable $Jmolroot
- PHP variables can be recognised because they start with a $ sign, whereas in this work
JavaScript variables do not. $Jmolroot is set to the address of JmolFolder,
containing the Jmol system files, relative to the present script
- This is put here for convenience, so that if this script is copied to a different
directory for use with a different set of models, the address may easily be found and edited if
necessary. Further down, you will see little snippets of PHP code
<?php echo $Jmolroot; ?>
inserted to put this path definition in all the
right places in the JavaScript
- Next come two if ... else ... statements which fish the two parameters out of the
query string only if they are present, and put them into local PHP variables $use
and $filestem. If they are not sent, default values are provided
- Further down there are snippets of PHP code to put the value in $use into
the JavaScript variable Info.use and the value of $filestem into the JavaScript
variable filestem
- In two places in the JavaScript code, the JavaScript variable filestem is then
simply added to literal strings to be sent to the Jmol applet
- You may test the working of the PHP code if you open the showjmol.php window
as a new tab, by clicking the following link,
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/muchiral/showjmol.php?use=HTML5&filestem=b1df
then change the query string in the address box of your browser,
replacing b1df by ax1hf
- You will see a different model
Putting it together: a page offering a choice of Jmol models to display
- The page to provide the user with a choice uses a HTML form which has
buttons corresponding to the models available for selection
- The showjmol.php script described above needs to be sent values for $use, to control which
kind of applet to load, and for $filestem to determine which model the applet
should present
- One way of doing this is for the HTML form to be delivered by a .php script
which is called again when the user clicks on the form. The form sends
back the selected option together with any options which have been selected
already. In this way, any number of options can be provided for, though
in the present example there are only two
- As soon as the user has selected the model, having already changed the $use mode if
desired, the .php script sends some JavaScript to open a new window in which the applet
will show the model
- To see a demonstration page in a separate window, use the following link:
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/muchiral.php
- If you view the page source of this immediately after opening it, before
you select a model to view, you will see nothing to open the showjmol.php window.
There are just two HTML forms, one to select the type of applet to be used,
and the other to select a model to be shown. Both call the current web
page again, which in modern browsers can be done using a null string for the form's
action address
- If now you click on one of the model buttons, a showjmol window will open.
Now reselect the calling page window and right mouse click to get another page source
listing. Scroll right to the bottom of the listing, where you will now see
that a JavaScript has been delivered, which opened the showjmol model window
and shifted the browser focus to it
- You may see the PHP code of muchiral.php, in a separate window:
https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/muchiral.php.html
- The script starts with an assignment to $filesdir of the relative address of
the directory which contains the model files and the version of showjmol.php which
is to be used
- Next the script looks to see whether values for $outputype or $filestem
have been received from a previous use of either of the forms, and if not it sets
them to default values. Notice that the method used by the forms for sending
the data is 'post', so that the user does not see them in a query string appended
to the web address of the page. This means that the script looks in the
PHP global variable $_POST for values, rather than in $_GET as was the case for the
showjmol.php script
- Notice too that the local mode variable is called $outputype rather than
$use, which is what will be passed on to showjmol.php. This is because
what is returned by the form in the present script is what appears as a label on
the button, which is meant to be easily understood by the user, rather than
what needs to be sent to the Jmol applet by showjmol.php
- Now the script delivers the HTML code for the page. This starts with
metadata in the head section
- The charset assigned allows for the use of &...: codes while not being too
modern for old browsers. Assigning description and author may be of some
use in getting search engines to see the page
- The title set in the head section is what appears on the title bar of the browser
window and on the browser tab if this is in use. It is seen by search engines
- The body section does not start with the main heading which the user will see
and which defines the chemistry:
this will appear a little later, after the web page technicalities have
been deal with, in a section for setting the use mode
- The user is told about the choices on offer, for which the form then presents the buttons,
then the user is told what the current state is, in a piece of text into which
PHP has filled the current value of $outputype
- If the user clicks the button for the option other than the current one,
they will see this text change, as the page is redelivered by muchiral.php with
only this change
- The buttons are produced by HTML form input elements of type 'submit'.
There are other ways of doing this, but this method allows good compatibility
with older browsers. It does, however, restrict the text on the buttons to
plain text without spaces: hence the use of underlines
- The options could have included ones other than using Jmol to show
a model: if you look at the
full version of this web page,
you will see that the user may instead choose a Chime model, if they still have
a 32-bit machine with a Chime-enabled browser. In that case the model .spt
file is called directly, instead of calling showjmol.php and sending the address
of the model .spt file
- If you are going to try out the model selection buttons later, you should
use the buttons to set the use mode in the demonstration page window,
according to whether your browser is Java-enabled or not
- This form does not send back a previously set value of $filestem, when you
change the use mode, but the model windows will be replaced with models using the
new mode if you select their buttons again in muchiral.php
- The next form, to select the model, is now started, while in the part of the
code not specific to this particular page. It starts with an input tag
of type 'hidden' which, when the form is submitted, will send back the current
value of $outputype, which PHP has filled in at that point in the HTML code.
This, along with the value of $filestem which will be set when the user
clicks a model button, makes up the information needed to complete the
definition of the model
- Now we come to the chemistry part of the page, which starts with the main
heading. This is the title of the journal article which the full version of
this web page supports, and is followed by the rest of the reference to the article
- I wanted to present models from two levels of calculation for each molecule, so
I have used HTML tables to set these out with suitable headings
- Besides using symbols from the paper to identify the molecules, I like to
include static images of the Jmol models, which I hope may help the user to
see the differences between the molecules and hence to relate to the paper,
before clicking to see the corresponding rotatable Jmol model
- These images were obtained by using Windows Snipping Tool on the Jmol model
in a suitable orientation, to produce a .jpg file. This was uploaded to
Linux and scaled using the Image Magick command 'display'. The dimensions
to put in the HTML code were then obtained by looking at the properties of the
resulting .jpg file using Windows Explorer
- The labels on the buttons are the values to go into $filestem and hence make
the file names of the model files. While these are arbitrary, they do
get put into the title in the showjmol.php web page header and hence appear in the
title bar of the model window. When several model window tabs are open,
this enables the user to identify which one is which
- After the </table> and </form> closing tags there comes some PHP code which
starts with 'if ($filestem) {'
- This tests whether $filestem has a value (other than 'false' or '0').
- The default for $filestem was unset, so on first calling of the page
the test will be false and the action will not be done
- When the user selects a model, the page is called again, with $filestem set,
so now the action in the PHP script takes place
- The corresponding closing brace } is at the fourth line from the bottom of the whole
file, when PHP script is restarted after some JavaScript has been delivered to open
the model window. Meanwhile, there is more PHP code with actions which are
nested inside this parent action. Some indenting of the code is useful
to ensure that each level has an opening brace { and a closing brace } at the same
indent position
- The second PHP statement in the top-level action is 'switch($outputype)'
followed by two cases. These each translate from the button
label for the use mode to the value of $use which will be sent
to the showjmol script, and build it in to the query string, followed by
$filestem. The whole
relative address of showjmol.php, with the query string, is assigned to
PHP variable $filename
- Finally, the PHP script ends temporarily so that JavaScript may be sent
to open the model window
- Into this, little snips of PHP code have put the values of $filename (for the
address), $winname (for the name of the window) and $filestem (for the id label
of the table cell containing the button clicked by the user)
- If the user returns to the page and selects the same model, it will go in the
same window as the previous call, replacing it, because the window has the same name.
Otherwise, a new window is opened for each different model, so that the
user may compare them
- The final statement in the top-level PHP action is 'unset($filestem)'.
This means that the page will not call showjmol.php again until the
user selects a model again
- The lengthy piece of JavaScript beginning with the comment
'Open the window for the selected model'
is mostly to deal with browsers which do not open popup windows when
instructed by JavaScript to do so in a web page like this one,
and do not ask the user for permission to do so
- (For browsers which do open popups, usually after asking the user once,
a call to the first function of this block is sufficient)
- The top level of JavaScript starts after the comment
'Script to show a model, by some means'
- PHP puts the values of $filename and $winname into JavaScript variables
filename and windname respectively, then tries to use the first function
to open the popup window. Only if this fails, because the browser
refuses to open the popup, will the rest of the script be used
- Notice that this JavaScript is not inside a function: if it were, then
the values set by PHP on variables filename and windname, before download,
would not be known to a different function, called independently
- The script is heavily commented, partly to remind me of how it works, if
it is to be copied to other web pages
- At the time of writing this, at least one common browser silently refuses
to open popups unless the action is directly the result of the user clicking
a button on the current instance of the web page, so the rest of the script
is to create a large and visible button, labelled 'Continue', which when
clicked will instigate the action. This button is created locally
by the browser, not downloaded from the server as are the other buttons
on the page
- A tree of JavaScript objects,
including the 'Continue' button, is built up and attached to the table cell
containing the submit button previously clicked
- The 'Continue' button is given an onclick attribute, to call the
second function defined above
- This in turn calls the first function, which is now likely to work,
because the sequence of calls is coming from a user clicking event,
rather than from a script started on page load. If it does not,
e.g. because the device does not support multiple windows, then the function
replaces the current window with the model window instead of producing a popup
- This sacrifices the ability to see and compare multiple models at the same
time, but at least the user may see the latest model called for