Difference between revisions of "Jmol JavaScript Object/Legacy"

From Jmol
Jump to navigation Jump to search
(Converting legacy web pages -> new subpage)
 
(old vs. new functions)
Line 1: Line 1:
 
== Converting legacy web pages to JSmol ==
 
== Converting legacy web pages to JSmol ==
  
=== Converting pages from Jmol to JSmol ===
+
=== Overview ===
 
It is not hard to convert pages that used the Jmol Applet to use the HTML5 versions of JSmol. The basic sequence includes:
 
It is not hard to convert pages that used the Jmol Applet to use the HTML5 versions of JSmol. The basic sequence includes:
  
Line 19: Line 19:
 
-- also included in the distribution: {{file|jsmol.zip}} > {{folder|js}} > {{file|JSmolApi.js}}
 
-- also included in the distribution: {{file|jsmol.zip}} > {{folder|js}} > {{file|JSmolApi.js}}
 
You might consider taking this opportunity to find out how jQuery works, if you are not familiar with it, and work more with those functions.
 
You might consider taking this opportunity to find out how jQuery works, if you are not familiar with it, and work more with those functions.
 +
 +
=== Table of equivalence old vs. new functions ===
 +
{| class="wikitable"
 +
|-
 +
! Legacy (Jmol.js) !! New (JSmol.min.js)
 +
|-
 +
| jmolInitialize || properties of the <code>Info</code> 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 || <code>color</code> property of the <code>Info</code> variable
 +
|-
 +
| 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 <code>save orientation</code> command
 +
|-
 +
| jmolRestoreOrientation || use Jmol.script with <code>restore orientation</code> command
 +
|-
 +
| jmolRestoreOrientationDelayed || use Jmol.script with <code>restore orientation</code> command
 +
|-
 +
| jmolSetDocument || Jmol.setDocument, usually in combination with Jmol.getAppletHtml
 +
|}
  
 
=== Conversion using the Jmol2.js 'adapter' library ===
 
=== Conversion using the Jmol2.js 'adapter' library ===

Revision as of 11:08, 20 November 2019

Converting legacy web pages to JSmol

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 File icon.gifJmol.js to File icon.gifJSmol.min.js
  • Adding the Folder icon.gifj2s folder/directory to your website.
  • Setting parameters in the Info variable.
  • Modifying function calls from the format jmolXxxx(..., appletExtension) to Jmol.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.

The main methods formerly implemented in File icon.gifJmol.js (and more!) have now equivalent functions that can be found in JSmolApi.js -- also included in the distribution: File icon.gifjsmol.zip > Folder icon.gifjs > File icon.gifJSmolApi.js You might consider taking this opportunity to find out how jQuery works, if you are not familiar with it, and work more with those functions.

Table of equivalence old vs. new functions

Legacy (Jmol.js) New (JSmol.min.js)
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
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:
  • Step 1
    • In all your pages, add a call to File icon.gifJSmol.min.js
    • In all your pages, change the existing call to File icon.gifJmol.js into File icon.gifJmol2.js
  • Step 1
    • Open in a text editor both File icon.gifJSmol.min.js, File icon.gifJmol2.js and a new blank document. Combine in this document the contents of File icon.gifJSmol.min.js followed by the contents of File icon.gifJmol2.js. Save this new document as File icon.gifJmol.js
    • Do not change your pages, keep the existing call to File icon.gifJmol.js
  • Step 2:
    • Add the JSmol files and folders as appropriate †
  • Step 2:
    • Add the JSmol files and folders as appropriate †

(†) 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 File icon.gifJmol2.js :

Upgrading Jmol without using JSmol

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 File icon.gifJmolAppletSigned0*.jar files in the Folder icon.gifapplet directory (you should not be using the File icon.gifJmolApplet0*.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.

Contributors

AngelHerraez