Jmol JavaScript Object/Legacy
Converting legacy web pages to JSmol
Contents
Overview
It is not hard to convert pages that used the Jmol Applet to use the HTML5 versions of JSmol. The basic sequence includes:
- Switching from
Jmol.js to JSmol.min.js - Adding the
j2s folder/directory to your website. - Setting parameters in the
Infovariable. - Modifying function calls from the format
jmolXxxx(..., appletExtension)toJmol.jmolXxxx(appletID, ...)(see below). Depending upon the magnitude of the problem, you may want to write (but read the next section first!) a set of JavaScript functions that allow you to keep your page source code unchanged. For example, if you use the simplest form of jmolButton, the converting function would be:
function jmolButton(script, label) {
Jmol.jmolButton(myJmol, script, label)
}
Or you can modify your page source code to use the new format. Or, easiest solution, use the 'adapter' library described below.
Table of equivalence old vs. new functions
The main methods formerly implemented in 
Jmol.js (and more!) have now equivalent functions that can be found in JSmolApi.js
-- also included in the distribution: jsmol.zip > 
js > JSmolApi.js
| Legacy (Jmol.js) | New (JSmol.min.js) |
|---|---|
| documentation | documentation |
| jmolInitialize | properties of the Info variable
|
| jmolApplet | Jmol.getApplet or Jmol.getAppletHtml |
| jmolButton | Jmol.jmolButton |
| jmolLink | Jmol.jmolLink |
| jmolCheckbox | Jmol.jmolCheckbox |
| jmolRadioGroup | Jmol.jmolRadioGroup or Jmol.jmolRadio |
| jmolMenu | Jmol.jmolMenu |
| jmolSetAppletColor | color property of the Info variable, or use the background command in a script
|
| jmolResizeApplet | Jmol.resizeApplet |
| jmolHtml | Jmol.jmolHtml |
| jmolBr | Jmol.jmolBr |
| jmolScript | Jmol.script |
| jmolScriptWait | Jmol.scriptWait, but you should consider using Jmol.evaluateVar instead |
| jmolScriptWaitAsArray | Jmol.scriptWaitAsArray |
| jmolCommandInput | Jmol.jmolCommandInput |
| jmolSaveOrientation | use Jmol.script with save orientation command
|
| jmolRestoreOrientation | use Jmol.script with restore orientation command
|
| jmolRestoreOrientationDelayed | use Jmol.script with restore orientation command
|
| jmolSetDocument | Jmol.setDocument, usually in combination with Jmol.getAppletHtml |
Conversion using the Jmol2.js 'adapter' library
What has been just described (i.e., writing custom functions that allow to keep using the old calls as used with Jmol.js) has been implemented in a special new Jmol2.js 'adapter' library. If you use this, you can leave your existing calls to jmolApplet(), jmolButton(), jmolLink() etc. You just need to:
| method A: | method B: |
|---|---|
|
|
|
|
(†) That is described in the Installation and Initialization sections of this page.
For more details, read inside the Jmol2.js file itself.
Locations to get Jmol2.js :
- In the Jmol download, Jmol-14.x.x-binary.zip > jsmol.zip > jsmol\js\Jmol2.js
- In the JSmol repository
- at StOlaf
Upgrading Jmol without using JSmol
Note: since suport for Java applets is being removed from all major browsers, this procedure will most likely not work any more.
If you have a legacy site that uses Jmol.js, and you would prefer to stick with Java and just upgrade your site so that it still works, then all you have to do is the following:
- Download the latest Jmol ZIP file distribution.
- Extract all the JmolAppletSigned0*.jar files in the applet directory (you should not be using the JmolApplet0*.jar files any more, unless you are certain what you are doing, since the unsigned applet will be blocked in browsers).
- Use the most recent version of Jmol.js that you have, or retrieve it from St. Olaf.
- Upgrade your site's Jmol.js and your JAR files with the files you have extracted.
Everything should work as before, but users will see a much kinder, more welcoming warning message the first time they access the new applet. Of course they will still have to give permission for the applet to be run, maybe in several dialogs. Please be aware that most users will not be able to see Jmol applets in their browser.
Converting the oldest Jmol pages that used the <applet> syntax
The very ancient syntax (dating up to 2006 at least) for including Jmol Java applets in web pages used the html <applet> tag for both the Jmol panels and the buttons acting on them.
Both were embedded in the page by using just the JmolApplet.jar file and specific applet tags.
Of course, with time web browsers abandoned the use of embedded Java applets and hence Jmol, then JSmol, evolved to new syntaxes, first with the use of the Jmol.js library (to facilitate the insertion of applets as such or as embed tags) and later with the JSmol.min.js library and its accessory files (to switch to fully html5-compliant objects instead of applets).
So there are old pages that used the <applet> tags, and here is a method to resuscitate them without rewriting all their code to new JSmol syntax, just by adding calls to two JavaScript files. You only need the standard files composing the JSmol library (included in downloadable Jmol distribution) and an additional adapter file: convertJmolApplets.js.
Instructions:
In the folder that contains your pages (or elsewhere if you adjust the paths), add these items extracted from the jsmol.zip package which is, in turn, contained in the downloaded distribution of Jmol:
- the whole j2s folder
- the whole php folder
- the JSmol.min.js file
- the 'adapter' library, convertJmolApplets.js (extracted from this zipfile)
Then, in the head section of your page, include the calls to both js files, something like this:
<script src="JSmol.min.js"></script> <script src="convertJmolApplets.js"></script>
That's all !
Save the modified page and test it in the web browser.
If you need help, do not hesitate to contact the jmol-users list or AngelHerraez (talk)
