This is a technical document about PE's construction -- you do not need to read it to use PE! It is provided for those who may be interested in adapting some downloaded PE javascript to their own applications.

Abbreviations used in this document: IE Microsoft's Internet Explorer browser; JS javascript/JScript; NS Netscape's browser; PE Protein Explorer;

PE could not have been developed as quickly as it has been, in a few years by one person with a day job, unless it was built upon MDL Chime. MDL Chime contains a great deal of power, and PE attempts to make that power accessible to a wide audience, as well as to extend it with new routines plus a knowledge base. The power derives largely from that built into RasMol by Roger Sayle. Roger's code for rendering and command processing was adapted for Chime by Tim Maffett at MDL. Tim also added a lot of power, and was kind enough to implement numerous suggestions of mine in Chime, which enabled me to build many Chime resources later. Bryan van Vliet Jean Holt, and Franklin Adler also made substantial contributions to Chime 2.

Chime was implemented by Tim Maffett as a Netscape plugin at a time when Netscape was by far the most popular browser (1995-1998 or so). Later, IE became more popular than NS due to Microsoft's aggressive and monopolistic marketing tactics (bundling IE with the operating system, and integrating it into the operating system, and making it impossible to uninstall). MDL has made continuing efforts to enable Chime to work to some degree, with no help from Microsoft, which never implemented the LiveConnect method for communicating with plugins. In summer, 2001, Microsoft suddenly and unexpectedly announced that IE 5.5 SP2 would no longer have support for "Netscape plugins". Amazingly, MDL managed to release Chime 2.6 SP3 by October 2001, able to work in the crippled IE version.

Luckily, before he implemented the LiveConnect function executeScript() in Chime, Tim Maffett had implemented a "temporary kludge", namely an "immediate mode" Chime button that could be written into an invisible frame and would execute automatically without being clicked (see downloadable example). This enabled a JS string variable containing a command script to be passed to Chime. Luckily, because this is the only method that works in IE, and thankfully, because MDL never removed this "kludge" from later versions of Chime.

Jean-Philippe Demers, then a high school student in Montreal, had been arguing persuasively for about a year that it should be possible to get PE to work in IE. In spring, 2001, I decided not to try it because I was worried about the time it would take, and that either it would not work, or would be unstable and crash too often. In summer, 2001, Paul Pillot, a secondary school teacher in France, sent me a version of PE that demonstrated the feasability of working in IE. It worked smoothly and did not crash! (Paul spent many weeks of his spare time on this, on a volunteer basis!) So I was convinced that it would be possible, but then Microsoft made its surprise announcement (see above). Finally after MDL released Chime 2.6 SP3, I began a serious effort to release PE able to work in IE in late November, 2001, using Pillot's code as a start.

At the time of this writing, MDL does not support MacPPC IE in Chime. Therefore PE can work in IE on Windows, but not Macintosh.

Browser Testing

PE refuses to start if the browser will not support it, in which case the goal is that it should behave gracefully, e.g. explain clearly what the problem is and offer solutions. Also, each refusal page offers a bypass link for use in case PE's browser tests are not working correctly. This could easily happen with new versions of browsers or Chime, or in tests on nonstandard platforms such as x86 linux. The following browser compatibility tests are performed in the following order by pe.htm (see browser_ok()). Except for the first, these can be bypassed by adding the query parameter "nbc=1" (No Browser Check), e.g. "pe.htm?nbc=1&".

1. JS: If JS is not operating, no other tests can be performed (and PE cannot operate). In this case, a large red error message appears on the FrontDoor (index.htm), and in pe.htm (the only legal entry point), explaining how to enable it. This can be tested easily by disabling JS and reloading.

2. If the browser is Navigator version 3, Internet Explorer prior to version 5.5, or a browser neither NS nor IE, pe.htm gives this message.

3. Platform: If JS detects a platform other than MacPPC or Win32, or if JS cannot reliably detect the platform (happens in old browsers or some uncommon browsers), PE displays needplat.htm.

4. Browser: If MacPPC IE is the browser, PE displays needbrow.htm. (Note that this document displays the current browser name and version, which may be compatible if you click the above link. Note also that on a Mac, the paragraph about updating IE does not appear.)

5. Old versions of Win32 IE: If the browser is IE of a version prior to 5.5 SP2, PE displays needbrow.htm?too_old. (Note that this document displays the current browser name and version, which may be compatible if you click the above link.) If the version of Win32 IE is newer than 5.5 SP2, PE assumes it will work (good luck!).

6. Netscape 6: If the browser is Netscape with a version greater than 4.999, PE displays needbrow.htm. (Note that this document displays the current browser name and version, which may be compatible if you click the above link.) Netscape 6.2 reports its version in navigator.appVersion as "5", consistent with its many other inadequacies!

7. If the tests reached this point, we have a compatible browser and platform. If java is disabled, PE displays needjava.htm.

8. A cookie is saved and read back. If this fails, PE displays needcook.htm.

   If all tests are passed at this point, the platform and browser and browser version are compatible, and the browser has javascript, java, and cookies enabled.
    
   Chime Testing

   Outline:

   • pe.htm
     Determines platform, browser, and browser version compatibility using javascript navigator objects.
     If Netscape, determines Chime presence and version using javascript navigator.plugins array.
   • chimtest.htm (IE only)
     Detects absence of Chime.
     Distinguishes Chime 2.6 SP4 from earlier versions, using "show version".
   • chimtes2.htm (IE only)
     Uses "show pdbheader" command to distinguish Chime 2.6 and later from earlier versions. Earlier versions are incompatible.
   • chimtes3.htm (IE only)
     Checks for previous testing (using a "cookie") and starts PE without intervention if user has previously reported Chime 2.6 SP3.
     If necessary, asks user to report version of Chime manually. If Chime is 2.6 SP3, records this in a cookie.
   • peow.htm (next step for any of the previous steps when a compatible Chime version is established):
     Opens a window of appropriate size, loading cmpo_rso.htm.
   • cmpo_rso.htm
     Checks size of window in which it finds itself. If adequately large, starts PE without intervention. If not, makes suggestions and offers options to user.
     Decides whether to start Explorer or Comparator.
   • fs_1.htm, fs_cmp.htm Explorer or Comparator framesets.
     If chime speed has not been recorded for the client computer, it is determined and recorded.
     Command frame is loaded first. Completion triggers the next step.
     Chime frame is loaded. Completion triggers the next step.
     Control frame is loaded. Completion triggers the next step.
     Molecule(s) (PDB file[s]) loaded.

9. In NS, the navigator.plugins array makes testing easy. For PE 1.91, Chime 2.0.3 is the earliest adequate version. If Chime is not installed, or if an earlier version is installed (including "beta" versions), PE displays needchns.htm. Later versions are assumed to be OK.

10. When Chime 2.6 SP4 was released (Sept 12, 2002) its navigator.plugins[i].name format changed from "Chemscape Chime 2.6 SP3" (or "Chemscape Chime 2.0.3") to "MDL® Chime 2.6 SP4". This required revisions in shared/n4c2.js, notably in chiv2().

11. In Windows IE, navigator.plugins is not implemented. (Curiously, it is in Mac IE, but Chime does not support Mac IE.) Chime 2.6SP3 is the earliest version that works with WinIE 5.5SP2, required for PE. Tamas Gunda worked out a detection method, adapted by Paul Pillot and re-designed by Eric Martz. The sequence of events below was redesigned between PE 1.91-1.981 (for Chime 2.6 SP3) and 1.982 (Chime 2.6 SP3 or SP4). It was necessary to support both SP3 and SP4 (rather than simply requiring SP4) because some teaching computer labs cannot change their software quickly. This made the test sequence below considerably more complicated.
    1. In pe.htm, if the browser is Netscape, chime_version_ok() is called which uses the navigator.plugins array to determine the version of Chime, and either fails (going to needchns.htm as mentioned above), or succeeds, going to peow.htm ("peow" stands for PE Open Window). The assumption in peow.htm is that all testing was completed and the browser is compatible. In other words, peow.htm attempts to start PE unconditionally, by opening an appropriately sized window containing the document cmpo_rso.htm. That document checks the window size and, if it is too small, makes recommendations to the user. If it is adequately large, it proceeds without user intervention to replace itself with either fs_1.htm (explorer) or fs_cmp.htm (comparator).

    2. If the browser is IE, pe.htm replaces itself with chimtest.htm. This document embeds an invisible (2x2 pixel) Chime, loading 1atom.htm, with a MessageCallback, and a script "show version". If no message comes back within 7 seconds, Chime is not installed, so PE displays needchie.htm.

    3. If "show version" produces the message "MDL® Chime 2.6 SP4" (or a later SP number) Chime is compatible and PE proceeds to peow.htm. (MDL implemented this "show version" report in SP4 at my request.)

    4. If the "show version" message contains the word "Chemscape", the version of Chime installed needs further testing, and chimtest.htm replaces itself with chimtes2.htm. (All versions of Chime prior to 2.6 SP4 inappropriately reply to "show version" with "Chemscape Chime 1.0". The "Chemscape" name was discontinued by MDL some time ago.)

    5. chimtes2.htm also uses a tiny, invisible Chime, but sends the command "show pdbheader". If the message "Invalid command argument" comes back, Chime is installed, but older than 2.6 (when "show pdbheader" was first implemented [at my request]), so PE displays needchie.htm?too_old.

    6. If the message "No pdb header available." comes back, the installed Chime is 2.6, but could be 2.6, 2.6SP1, 2.6SP2, or 2.6SP3. In this case, the only option seems to be to ask the user to check Chime's version. This is done in chimtes3.htm. If the user reports that the version is earlier than SP3, needchie.htm is displayed. In this case, no cookie is set (see next step), so PE will ask the user what version of Chime is installed on every future attempt, unless 2.6 SP4 is installed (in which case we don't get to chimtes3.htm).

    7. If Chime's version is reported by the user to be 2.6 SP3, chimtes3.htm saves a cookie (lifetime: one year) that contains the version and subversion number of IE. It then replaces itself with peow.htm, starting PE.

    8. The purpose of the cookie is to avoid annoying the user with a request to specify the currently installed version of Chime for every PE session. Upon every subsequent start of IE, the version in the cookie is compared with the version of IE. If IE's version changes, the tests are run again. If not, the tests are not made again, and PE attempts to start. This means that if the user later uninstalls Chime, or installs an earlier version of Chime 2.6, PE will try to start, but fail to work, without any error message.

    9. If the user inappropriately reports SP3 (e.g. when the actual version installed is SP2) PE will fail to work. The only fix for this is to clear the cookie, which can be done by closing the window that results from this link: clear the cookie.