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. File pe.htm detects Opera and Safari. If either of these browsers is being used, it explains that they are incompatible and offers a link to needbrow.htm. If the browser is neither of these, file pe2.htm is loaded, which conducts the remaining browser compatibility tests.
   The tests for these two browsers had to be separated because neither allowed the existing (complex) browser testing javascript to be accessed. Opera 7.23 goes into an infinite reloading loop when the URL query parameter contains unescaped slashes, and when any assignment to document.location.href is made. Such query parameters are long established as permissible for PE and are present in many user's custom web pages around the world. We did not spend the time to diagnose why Safari failed to process the existing javascript in the same way as IE 6 and Netscape 4.

3. 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.

4. 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.

5. 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.)

6. 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!).

7. Netscape 6/7: 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.)

8. If the tests reached this point, we have a compatible browser and platform. If java is disabled, PE displays needjava.htm. In Netscape 4 and IE prior to Win XP, java had to be enabled in order for javascript to work. In Win XP SP2, the test for java failed when PE was running from a CD. Therefore, for Win XP SP2, the java test is not performed (regardless of whether running from a CD). Note that java is not included in Win XP.

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

10. Detection of popup window blockers: While the above tests were being performed, a small window was opened, which changes variable pop_opened to true in its parent (opener) window and then closes itself. pe2.htm refuses to proceed with PE startup until pop_opened is true. If it remains false for 6 seconds, PE concludes that the browser is blocking it from opening windows (absolutely necessary for its function) and displays popfail.htm. (The code for this testing is in pe2.htm and popcheck.js).
    Win XP SP2 IE has a built-in pop-up blocker which is on by default. PE had to be adjusted to avoid going to a new document if the pop-up test fails, because going to a new document hides the information bar, which gives access to enabling pop-ups.

    The Win XP SP2 pop-up blocker does not interfere with downloaded PE. However, for downloaded files, or files from a CD, one must give permisson for "active content" in IE. Again, this is done via the information bar.

    Therefore, all instructions regarding enabling pop-ups and active content must appear on the page that does the testing, not a new document. chimtest.htm, displayed only when IE is used, shows these instructions. To see them, go to the FrontDoor in IE, check "Start step by step", and start PE. Note that instructions in red are shown only when you are in WinXP SP2.

    If all tests are passed at this point, the platform and browser and browser version are compatible, the browser has javascript, java (if not WinXP), and cookies enabled, and it permits PE to open new windows as needed.
     
    Chime Testing

    Outline (details are below this outline):

    • pe.htm, pe2.htm
      Determine platform, browser, and browser version compatibility.
      If Netscape, determines Chime presence and version using javascript navigator.plugins array.
    • If IE: go to chimtest.htm (IE only)
      Detects absence of Chime.
      Distinguishes Chime 2.6 SP4 from earlier versions, using "show version".
      As of PE 2.3 Alpha, Chime 2.6 SP4 is the earliest acceptable version.
    • fs_peow.htm (next step for any of the previous steps when a compatible Chime version is established):
      Uses wincook.htm to retrieve the window size preference, then loads peow.htm in the other frame, which opens a window of appropriate size. This window loads fs_rso.htm.
    • fs_rso.htm ("rso" refers to "window resize option").
      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.
      THIS NEEDS TO BE REVISED:
      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.

11. In NS, the navigator.plugins array makes testing easy. For PE 2.3 Alpha and later, Chime 2.6 SP4 is the earliest acceptable 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.

12. 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/browget.js, notably in chiv2().

13. 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). For PE 1.982 (fall 2002), 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 considerably more complicated. Beginning with PE 2.3 Alpha, Chime 2.6 SP4 is required. This simplified the testing sequence (eliminating the earlier stages in chimtes2.htm and chimtes3.htm).
    1. In pe2.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 fs_peow.htm ("peow" stands for PE Open Window). The assumption in fs_peow.htm is that all testing was completed and the browser is compatible. In other words, fs_peow.htm attempts to start PE unconditionally, by opening an appropriately sized window containing the document fs_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, pe2.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 fs_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 is 2.6 SP3 or earlier, and the message in needchie.htm?too_old is displayed. (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. Versions prior to 2.6 SP3 fail to load in IE 5.5SP2 or later, and hence will be detected as the absence of Chime, even if "installed".)