DNATut2's HTML, javascript, and Chime-script

Terminology & Design

Terminology: DNATut2, NLCS2

I'll refer to the present Chime tutorial on DNA structure as DNATut version 2, or DNATut2. The html/javascript which controls the tutorial I'll call NonLinear Control Structure version 2, or NLCS2. Thus DNATut2 consists of the Chime-scripts and PDB files which define the DNA-specific content of the tutorial, plus NLCS2 (HTML and javascript), a portion of which is content-independent. NLCS2 can be adapted to tutorials on other subjects .

'Nonlinear' tutorials

By calling DNATut2 a 'nonlinear tutorial', I mean that it is a presentation with no particular beginning or ending. The sequence of images is selected by the user in a self-directed exploration. This is in contrast to a linear tutorial such as ProtSecS (see below).

'Linear' tutorials: ProtSecS, LCS2

Prior to the completion of DNATut2, a linear control structure had already been completed for a Chime presentation on protein secondary structure (ProtSecS), designed to illustrate a lecture. Unlike DNATut2, ProtSecS is a linear series of images designed to run from beginning to end. It is called ProtSecS and its html/javascript control structure is called LCS2.

Design assumptions for NCLS2

NLCS2 is designed to accomodate a series of short Chime-scripts, none of which contain pauses. Because this presentation is nonlinear, and because it has no pauses, there is no need for a continuous-play mode as there is in a paused linear presentation (e.g. ProtSecS/LCS2).

Creating a New Nonlinear Tutorial

Creating a new nonlinear tutorial involves a considerable amount of programming in three languages: HTML, Chime-script, and javascript. DNATut2 consists of about 1,000 lines each of HTML and javascript, and about 450 lines of Chime-script. Although the NLCS2 provided here will be useful, such a project will be time-consuming and is best undertaken by someone with programming experience. Although no compiler is needed (Chime interprets Chime-script; Netscape interprets HTML and javascript), standard programming tools needed include a plain-text editor. And a you will find it very useful to have handy a program able to find and report those files among all files in the current directory which contain a particular string (such as a member of the grep family of programs which supports wildcard filenames).

Here are steps one could follow to create a Chime tutorial about a different molecule, using a nonlinear button structure similar to that in DNATut2. DNATut2 was actually written in a much less organized fashion, and went through several different approaches before arriving at version 2. After the fact, I have tried to envision a more organized series of steps leading to a new tutorial. However I have not tested this method. If you try it, please let me know where these instructions need improvement.

  1. Design the content of the new tutorial.

    1. Select and explore the PDB file(s). Search for a PDB file (or files) which illustrate the structural features you wish to teach. It is probably easier to explore these molecules in RasMol, rather than Chime. Chime is capable of much more effective presentations, but is more complicated to use for preliminary explorations. All RasMol-script commands are supported in Chime.

    2. Divide topics into pages. Decide which topics in your presentation will best be separated into different HTML pages (files). Note that each topic with its own page, listed on the contents page of DNATut2, uses a different color scheme and/or different button functions.

    3. Design button functions. For each topic-page, decide what actions you want the buttons to perform, and how many buttons you will have. List a label for each button. Decide whether each button's function will be invariant (such as X spin), or will change according to which buttons were clicked before it. In DNATut2, buttons can be pushed in nearly any possible sequence. In order for this to produce appropriate results, the Chime-scripts invoked by each button required much fine-tuning during debugging. Yours probably will also.

    4. Do the buttons need a separate frame? Decide whether the same buttons can remain present on each topic-page at all times. In DNATut2, this is the case. If you will have several buttons which are relevant only when a particular view has been selected previously, you may prefer another strategy. You could have one button change the entire set of buttons available on the page. In order to do this without shutting down and restarting Chime (which is what happens when you return to the table of contents and pick a different section), you would need a separate frame to contain the buttons. If you are interested in trying this, you may find helpful the introduction to the use of frames with Chime.

  2. Implement the tutorial. A nonlinear tutorial is complex. In addition to writing Chime-script, you will have to write some javascript. With luck, you can simply vary the javascript present in DNATut2 without having to add entirely new code.

    1. Write a RasMol-script for each button.. You can probably use some of the Chime-scripts from buttons in DNATut2, while others may need to be entirely new. See the RasMol Manual, and the Guide to Script Creation for RasMol and Chime. Most of the content of each script will be RasMol commands (all of which work in Chime). Chime's command language includes a few additional commands, not available in RasMol, which are particularly important for movements and zooms and for controlling presentations. Therefore it will probably be simplest to develop your representations and color schemes initially in RasMol. A button can call one or more Chime-script files which were initially developed and tested in RasMol. For example, DNATut2's reset button calls the Chime-script file reset.spt. Test your button-script files in RasMol.

    2. Revise index.htm to present links into the topic pages you have designed.

    3. For each topic page, create a Chime-invoking HTM file, a frameset HTM file, and a button callback JS file. The Chime-invoking pages in DNATut2 are the HTML files dnapairs.htm, dnacode.htm, dnabone.htm, and dna53.htm. These files fill the main part of the screen and layout the buttons as well as invoking Chime. You could rename a copy of one of these and adapt it to your content. In order to support debugging and state-dependent scripts, you will need a frameset file. Rename, for example, the file fs_pairs.js and substitute the name of your htm file for dnapairs.htm in the frame named fr_mol. In addition to the Chime-invoking htm file and the frameset file, if any of your button-sent scripts are variable, you will need a button callback javascript file such as b_pairs.js. You can rename this file and adapt it to your content.

      Each button is defined in dnapairs.htm, but the scripts for most are generated in b_pairs.js using the ButtonCallback mechanism described in the section below on implementation.

    4. Add Chime-specific script commands. Smooth rotations, translations, zooms, and slab plane movements can be added with Chime's move command, as can clock-timed delays and anything which a Chime-script needs to do outside the plug-in itself by calling javascript functions. To test and debug the Chime-specific changes, use the built-in debug mode.

    5. Debug, polish, debug, polish, ...

DNATut2's Implementation

Simpler pages

The page on Strands (file dnabone.htm) has intentionally been left as simple as possible, to serve as an example. (This required that the debug mode not be implemented for this page.) In this simplest page, all the button-invoked Chime-scripts are invariant ones. That is, they perform exactly the same function regardless of the sequence of button pushes which preceded them. Therefore, they do not need javascript conditional tests of state variables, so they are included in-line directly in the html file. Note the complete absence of javascript in this file. It so happens that the Chime-scripts in the file dnabone.htm call no subscript files, another simplification, albeit coincidental.

When debug mode is off, the Strands page does not need the 'immediate button' mechanism (see below) to send to Chime a variable Chime-script dynamically-generated by javascript. Therefore it does not need a 'dummy' frame (see below) and hence uses no frames. This page consists of ordinary HTML including one <embed ...> tag to invoke Chime, plus one for each button.

The page on Ends (file dna53.htm) was as simple as that on Strands, but has been modified just enough to support the debug mode. This required the addition of certain javascript controls. By searching for the word javascript in this file, you can find all such instances. With debug mode on, this page needs the 'immediate button' mechanism, and hence frames are present.

Internet Explorer Compatibility

With the exception of this section, the remainder of this document is unchanged since the original implementation of version 2 of the DNA tutorial (1997). This section was added in June, 2002, for version 3.

Chime is a Netscape Plugin. This DNA tutorial (and all of my other Chime Resources) was originally designed to work in Netscape (Windows or Macintosh). Later, MDL adapted Chime to work in Internet Explorer (IE, Windows only). Chime's operation in IE suffers from a number of bugs and idiosyncracies that differ from its behavior in Netscape. These are documented in Protein Explorer (see release notes under version history for version 1.922), and those relevant to this DNA tutorial are explained below.

The simple design in dnabones.htm works in IE. That is, embed tags that specify buttons containing invariant command scripts work in IE, provided that none of the command scripts reference PDB or script files (see below).

Command scripts can be placed in javascript strings (as explained below) and sent to Chime. When the DNA tutorial was written in 1996, there was only one method for doing this, the "immediate-mode button/dummy frame" (IMBIF) method (see chiimmed.js). Subsequently, a method called LiveConnect was introduced, but this only worked with Netscape. The IMBIF method used here works with both Netscape and IE.

The major bug in Chime (2.0.3 or 2.6SP3) in IE is that command script execution is halted whenever a command references a disk file, e.g. on every "load filename.pdb" or "script filename.spt" command. Execution of script disk files (filename.spt) also fails whenever a delay or move command is encountered. If the only file reference is a "script" command as the very last command in a script (and if the script file has no load nor script commands within it), execution may work. However, subsequent scripts may trigger re-execution of commands from previous scripts.

The safest workaround is to put all scripts into javascript string variables, and use scriptToChime(script) [defined in chiimmed.js] to send then to Chime. Delay and move commands work in such scripts; however, "load" or "script" commands still halt execution. Therefore, when the PDB file needs to be changed by some scripts, a special mechanism is required that sends 2 scripts, one load the PDB file, and a second to render and color the molecule. This is handled by loadscript(pdbfile, script) defined in chiimmed.js. In summary, most .spt files were eliminated in version 3. Scripts converted to javascript strings will be found in files s_pairs.js and s_code.js. (The original reset.spt is still used in b_pairs.js; this one didn't seem to cause any problems in IE.)

Some scripts in b_pairs.js are handled differently in IE than in Netscape (search for isIE), but for the most part, the changes required for IE are compatible with both Netscape and IE. File n4c2.js was added to detect IE and set the value of the boolean isIE.

Simple Javascript

The page on DNA Code (file dnacode.htm) uses the 2X zoom and 1/2X unzoom buttons. In order to prevent these from generating extreme excursions (which cause various undesirable anomalies), the maximum zoom is 1600% and the minimum, 100%. Maintainence of these limits requires a javascript variable so that when the button is pushed, the current size is known. Since the Chime-script (move command) sent to Chime is dynamically generated by javascript according to the preceding state, the 'immediate button' mechanism (see below) is needed, and this in turn requires a 'dummy' frame (see below).

The 'zoom' example is only one of several places where javascript is needed in this page. When this page displays a single base pair, the buttons labeled End and Replicate must issue different Chime-scripts than when the DNA helix is displayed. Also, in order for the Reset button to interrupt a slow movement, an interrupt must be sent to Chime via the 'immediate mode' (an interrupt fails via the ordinary embed button mechanism). These requirements necessitate the use of javascript to generate and send scripts to Chime in the DNA Code page. See the sections below on the immediate button mechanism and on more complex pages for more explanation of how this works.

Chime's 'immediate button' mechanism

The ability to construct a Chime-script dynamically from javascript code is a powerful one. It allows the Chime-script to be tailored to the state of the tutorial (see for example zoom limits above).

The method for sending the dynamically-constructed Chime-script, as a character string variable, to Chime is as follows. Javascript is used to to write a new document into a 'dummy' frame which is specified as size 0% of the window, therefore invisible. (See file fs_code.htm for a definition of the frameset for the dnacode.htm page.) The new document contains an <embed...> tag which creates a button for sending a Chime-script to Chime. This button is very like the many buttons visible in the tutorial, each of which, when clicked, sends a Chime-script to Chime. But this button differs in one crucial respect. The embed-tag contains the parameter immediate=true. This causes the Chime-script to be sent to Chime immediately, without waiting for the button to be clicked. In fact, not only is the frame containing this button too small to be noticable, but the button itself is also hidden. See chiimmed.js, which creates this embedded button.

More Complex Pages

The page on Base pairs (file dnapairs.htm), is more complex because both the invocation of Chime and nearly all the button-issued Chime-scripts are generated by state-variable dependent javascript. The invocation of Chime depends on whether or not debug-mode has been enabled. The Chime-scripts issued by most of the buttons change according to the previous buttons which were clicked, as recorded by javascript state variables.

Because the Chime-scripts vary, the HTML <embed...> tags, which create the Chime-script-sending buttons, do not themselves contain the Chime-scripts. Rather, when a Chime-plugin-targeted button is clicked, Chime sends the name of the button to javascript by calling a ButtonCallback function. The name of this function is specified in the <embed...> tag which creates the button (see button.js). This function, designed by the user, takes appropriate action; in this tutorial, it constructs the appropriate Chime-script and sends it to Chime via an immediate button mechanism. The ButtonCallback function is bcb() defined in the file button.js. It is called twice per button-push*. On the second call, bcb() passes the button name to bcb_action(), which is defined in the file b_pairs.js. This is where the variable Chime-scripts are generated for each button.

*The first call is before execution of the Chime-script, if any, given in the <embed...> tag which created the button. The second call is afterwards. In NLCS2, the embed tags contain no Chime-scripts, so the two calls are equivalent. A boolean ButtonCallback parameter indicates whether the call is before or after; this is used to avoid issuing each javascript-constructed Chime-script twice. See bcb() in button.js.