User:Eric Martz/JSmol Notes

From Proteopedia

proteopedia linkproteopedia link

Contents 1 Things To Be Aware Of Before Converting To JSmol 1.1 Advantages 1.2 Disadvantages 1.2.1 JSmol is slower than Jmol 1.2.2 Poor performance in Internet Explorer & Edge 2 Converting Websites from Jmol to JSmol 2.1 Get JSmol 2.2 Jmol.js -> Jmol2.js 2.3 jmolInitialize() 2.4 (to be continued) 2.5 Other Conversion Advice 3 Creating New Websites That Use JSmol 3.1 Starting Your New Website 4 See Also

Things To Be Aware Of Before Converting To JSmol

Advantages

Of course there are huge advantages to using JSmol:

• Users of a JSmol website do not need to install Java (which is a likely security risk).
• The very popular Google Chrome browser no longer supports Java, nor does Edge (the new browser in Windows 10). Opera plans to remove support for Java.
• A JSmol website will likely work on iPads and smart phones. (Java is not available for these platforms, so Jmol is not an option for them.)

Disadvantages

JSmol is slower than Jmol

Molecules of Various Sizes
PDB code	Atoms (Kilo)	kDa* (Asymmetric Unit)
1d66	1.7	24 (28)
2bvw	6	77 (87)
2v61	9	107 (120)
2cvo	12	142 (160)
5ibx	17	202 (215)
7ahl	23	220 (233)
1g3i	45	602 (826)
3j36	60	900
3j9q	99.6	1,314 (1,424)
2bbn	57 (2.7K x 21 NMR models. Includes hydrogen.)	416 = 19.8K x 21 NMR models (416)
Models with >10,000 atoms are in the largest ~10% of the PDB; with >20,000 atoms, the largest ~5%; with >50,000 atoms, the largest ~1.5% (counting all models for NMR ensembles). * kDa excluding water as reported by Jmol (print {not hoh}.mass.sum). RCSB molecular weights are sometimes much larger for obscure reasons. RCSB report is in parentheses.

JSmol is significantly slower than Jmol. Rotation will be jerkier (see JSmol/Rotation Speeds). Smaller molecules (<10,000 atoms) are handled quite well. Large molecules (>20,000 atoms; see table at right) may be slow to load and process. (Sometimes I’ve seen delays of up to a minute, even more, during which JSmol freezes. These delays tend to happen with large molecules but are not simply related to size.) Multiple-model ensembles (such as from NMR experiments) may cause JSmol to freeze while taking minutes to load the ensemble, or loading may never finish.

Here is how two websites that now use JSmol by default have handled these issues:

• FirstGlance in Jmol loads only the first model when there are more than one (in JSmol). It offers signed Jmol_S (Java) as an option (and a preference setting). The unsigned Jmol applet is no longer offered because it is deprecated and Oracle says that eventually it won't be allowed. FirstGlance recommends using Java when the molecule has >20,000 atoms, and even more strongly recommends it when >50,000 atoms.

• Proteopedia loads only amino acid alpha carbon atoms (or nucleic acid phosphorus atoms) and ligand atoms, since its ribbon view (secondary structure schematic) works fine without the other atoms. A prominent message is displayed that a simplified model is being shown, and there is a button to load the complete model. For registered users who are logged in, Proteopedia has a preference setting that will use Jmol_S instead of JSmol.

Poor performance in Internet Explorer & Edge

JSmol runs in the javascript of the browser. Different web browsers operate JSmol with very different performances (see JSmol/Rotation Speeds), and the performances vary as browser versions are updated. Internet Explorer has always been unacceptably slow (all versions, including version 11), but since early 2016, it is no longer the most widely used browser.

For current recommmendations, see JSmol/Rotation Speeds.

FirstGlance in Jmol detects the browser being used, and recommends the optimal browser when another browser is used.

Converting Websites from Jmol to JSmol

Get JSmol

1. Download Jmol. The download package includes both JSmol and the Jmol Java applet. Go to Jmol.Org, click Downloads.

2. Unzip the downloaded Jmol file. After unzipping, inside the main folder is jsmol.zip. Unzip that too.

3. Copy the jsmol folder (the one you unzipped in step 2) and all its contents (~2,000 files!) into the resource that you are upgrading. (You don’t need to copy any of the other files in the main folder.)

Jmol.js -> Jmol2.js

The following steps apply to the main html file of your resource:

4. Javascript files in the <header> section of the main html file. If the old page used Jmol.js, there will be a line like this that can be removed or commented out:

<!— COMMENT OUT THIS LINE
<script src="jmol/Jmol.js"></script>
 -->

Add these two lines. Jmol2.js replaces Jmol.js, defining the same functions you were already using in Jmol.js. The order of these two lines is critical: JSmol.min.js must come before Jmol2.js.

<script type="text/javascript" src="jsmol/JSmol.min.js"></script>
<script type="text/javascript" src="jsmol/js/Jmol2.js"></script>

jmolInitialize()

Find jmolInitialize() in your code. If necessary, change the relative directory path argument of this function to reflect the location of the jsmol directory you have added. For example, if your main html file is in folder1/folder2/main.html, and the location of jsmol is folder1/jsmol, then from main.html, jmolInitialize("../jsmol").

(to be continued)

I know that the above is incomplete. When I learn more I will add it here.

Other Conversion Advice

• Converting pages from Jmol to JSmol in the Jmol Wiki. This writeup is too technical for me to understand.

Creating New Websites That Use JSmol

Download and unzip the jsmol directory (see steps 1-3 in the previous section).

In the jsmol directory are various demonstration .htm files that illustrate uses of JSmol, such as jsmol.htm, a series lite.htm, lite2.htm, etc., a series simple.htm, simple1.htm, supersimple.htm, etc., test2.htm, etc.

Unfortunately, I know of no documentation for these demonstration files other than the files themselves.

There are two ways to preview these .htm files:

1. Substitute the filename for "jsmol.htm" at the end of the url http://chemapps.stolaf.edu/jmol/jsmol/jsmol.htm.
2. Drag the file from your local jsmol directory, and drop it into Firefox. This may not work in any browser other than Firefox.

Starting Your New Website

Here is one possible procedure:

• Choose one of the demonstration files that has features that you want to use in your website.
• Copy it into a new directory that also contains a copy of the jsmol directory with all the original files in that directory.
• Edit any references to files or directories in the jsmol directory to prefix those with "jsmol/", so the .htm file that is in the same directory with the jsmol directory can "find" those files. For example, in simple.htm, two changes are needed (additions in boldface):
  • <script type="text/javascript" src="jsmol/JSmol.min.js"></script>
  • j2sPath: "jsmol/j2s",
• After the above two changes, you can drag the file simple.htm into Firefox, and it works.
• Edit one thing at a time in your chosen, working demonstration file, save, and re-test. Thus you can gradually modify the demonstration file to become your desired website.

If you have questions or get stuck, please address your questions to the jmol-users email list.

See Also

• Jmol, where the four forms of Jmol are explained, and links are provided to other relevant articles.
• JSmol/Rotation Speeds for the 6 most popular browsers, without and with Java.