Design and Methods
ProtSecS/Linear Control Structure 2

by Eric Martz, December 1996


This brief, elementary introduction to protein secondary structure (ProtSecS) was designed as a linear 'movie' to be projected to a class to illustrate a lecture. The goal was for the presentation accompanied by the lecture to take about 10 minutes. Lysozyme was chosen because it is the example used in Chapter 5 of Biology, 4th edition, 1996, by Neil A. Campbell, Benjamin Cummings Publishing Co., Menlo Park CA US.

This Chime-script was originally written for RasMol (September, 1996). It was never put on the web in the RasMol form because of the importance of having a color key legend which could not be implemented satisfactorily in RasMol. It was ported to Chime in several stages late in 1996 while Chime itself was under rapid concurrent development to version 1.0. The advantages of Chime over RasMol for this kind of presentation are numerous. This implementation involves both html and javascript. My favorite introductions to html and javascript are listed below. Below you will also find introductions to script-writing for RasMol and Chime.

The control structure skeleton of this tutorial is designated Linear Control Structure version 2 (LCS2) for Chime presentations. (Version 1 utilized Chime version 0.99 and was put on the web November 6, 1996.) Detailed instructions are provided for building your own linear tutorial about the molecule(s) of your choice by substituting new content into the control structure provided here. A development/debugging mode has been provided to assist in this process.

The RasMol/Chime-script which generates this presentation consists of over 400 commands (lines). Amazingly, the javascript which controls the presentation consists of over 700 lines. The HTML which accompanies the presentation consists of over 650 lines (excluding the 400-some lines in this design document). Overall, this presentation, which lasts about 5 minutes if the pauses are minimized, comprises over 2,000 lines (about 10,000 words), exclusive of the PDB files involved. The amount of programming involved shows why you will likely find it worthwhile to use LCS2 should you wish to create a linear presentation of your own. You will still have to write hundreds of RasMol/Chime commands (see below for help), but you will be spared having to invent the javascript and most of the HTML.

Design Goals

The implementation was designed to provide smooth progress through the Chime-script. In particular, I avoided closing and re-invoking Chime, and creating new windows after the first one. The user is encouraged to rotate and zoom at all pauses; Chime's view restore command is used to restore proper image orientation immediately after each pause.

The next/replay/quit buttons were placed in the same position on the screen throughout the Chime-script so the lecturer can merely click without repositioning the mouse pointer in order to proceed. Since Chime itself provides no indication of when it is busy vs. when it is standing at a pause, the 'next' button changes from green to red when Chime is busy.

Mechanisms are provided to enter the Chime-script at any of five major sections, and to replay the current section. A continuous-play mode is provided for situations in which unattended operation is desired. A development/debugging mode is provided to assist when new content is installed into LCS2.

640 x 480 Pixel Projection Window

Most computer screen projectors presently have a resolution of 640 x 480 pixels. Moreover, this is ample resolution for such a projected image. An 800 x 600 or higher resolution image tends to have details not visible in the back of the room. Also, movements of the molecule are slower at higher resolution. Therefore, this Chime-script creates a fixed window exactly 640 x 480 pixels.

The 640x480 window is created by the javascript (js) function show64() in the file show64.js. Higher resolution could be achieved easily by changing the pixel dimensions specified in this function.

The display window is created without a menu (although one is present during debugging). This conveniently prevents bookmarking somewhere in the middle of the Chime-script.

Five Sections

The RasMol/Chime script is divided into 5 sections. The PDB files loaded at the start of each Chime-script file are indicated.

Starting the Tutorial

Since there are five possible entry points into the tutorial, and two modes (lecturing and development/debugging), there are a total of ten ways of starting. To avoid having ten different versions of the main Chime-script saved as 10 disk files, the main Chime-script is generated dynamically as a javascript variable called startup_script (see

It turned out that if the startup script were handed to Chime as part of its invocation (as the src in the embed tag), the Chime-script began executing before other parts of the frame containing Chime were ready (at least in debugging mode), e.g. the message display area was not yet in place when the first messages began arriving. The solution adopted is to invoke Chime with a dummy script file which does nothing. Upon exiting of the dummy script, detected by the MessageCallback function, the main script is sent to Chime (see msgcall.js).

Chime 1.0 does not report name of the Chime-script file used to invoke Chime in an <embed debugscript=on src=...> tag with a script filename.spt message. In contrast, all Chime-scripts called after Chime is invoked with a script command are so-messaged. This means that the monitor which displays the currently executing Chime-script is never informed of the invoking Chime-script file. In LCS2, neither the dummy invoking Chime-script file startup.spt nor the dynamically generated main Chime-script startup_script are reported in the Chime-script execution monitor. This seems acceptable since we are really only interested in the section-scripts (e.g. alpha1.spt) and their subscripts anyway.

Starting in the Middle

There are two situations in which one needs to start with a section other than the first: when selecting a desired starting point from the outline, and when pressing the yellow back button [<] to replay the current section.

Each of the five Chime-script section files starts by clearing the previous atomic coordinate file (zap), and loading the requisite PDB file. Although the last 4 sections all use the same PDB file (lysozyme.pdb), it was deemed unnecessary to avoid reloading this file since the time involved was hardly noticeable.


Roger Sayle introduced a pause command into RasMol. Pauses are used frequently in ProtSecS to allow the lecturer to say as much or as little as desired about each image.

In RasMol, a pause is released by pressing any key. In a web browser, however, the keystroke release mechanism is cumbersome, unfamiliar, and inappropriate. Therefore, Chime introduced a special pseudocommand 'unpause'. This is a pseudocommand because it does not work in the same way as other Chime-script commands, and of course would never be found in the middle of a Chime-script. When sent to Chime as the first and only command in a Chime-script, it releases the current pause. It can of course be sent by clicking on a familiar type of browser button or link, such as

or Next or

In order for the javascript to be able to take appropriate action when Chime executes a pause, Chime calls a javascript function each time it encounters a pause in the Chime-script, and each time a pause is released. The function to be called is designated when Chime is invoked with <embed ... > (see chime.js) with the syntax

where OnPauseCallback could be any function name specified by the user. See, for example, the OnPauseCallback defined in the file mainview.htm. The main functions of OnPauseCallback in LCS2 are to indicate when Chime is busy by changing the color of the forward-button, to clear the message textarea immediately after each pause when autoclear mode is enabled, and to manage continuous-play mode.


As the Chime graphic image changes, the legend must change. Each legend consists of a color key (implemented in html as a one-cell table) plus a short description. Fonts are large enough to read from a distance.

Legend-changing is accomplished by using Chime 1.0's new ability to execute javascript commands directly. For example, the first legend in ProtSecS (see alpha1.spt) is produced with the following Chime-commands:

legend.js to find out how "chon" specifies a CPK color-key, etc. Sometimes a Chime-script section begins by inheriting the legend from the previous section. Only when the user selects this section as the first to be shown (by starting with it, or replaying it) does the appropriate legend need to be produced. Although the penalty for producing the legend unconditionally (and hence redundantly if the section in question is not the first to be played) would not be serious, a function is provided to produce the legend only when needed. An example may be seen just prior to the first pause in alpha2.spt.

Development/Debugging Mode

Linear Control Structure version 2 introduces a built-in development/debugging mode. The tutorial, or any section of it, can be played in this mode (called debug mode for short). Debug mode allows you to see how the RasMol/Chime commands produce the images, to interrupt at any desired point, and to intervene with manually typed commands.

Debug mode provides a monitor frame at the top of the window. The monitor frame displays the name of the script file (and subscript files) being executed and the number of the script section which will be executed if the replay button [<] is pressed. The latter is set periodically by the RasMol/Chime script itself as it progresses. For example, to specify that section 3 should be the entry point if the replay button is pushed, the command is javascript set_replay(3).

An html form textarea shows each script command as it executes. Trace modes are provided for stopping after each script command (single stepping), stopping as each new script file is entered, or stopping when any user-specified word or phrase is encountered (trap mode). Upon stopping, an option is provided to interrupt the script, whereupon manually typed commands (including javascript commands!) can be executed.

Since the first script file will have started playing before access to the single-step trace button is provided, single-step tracing in the first script can be invoked by including the command 'javascript toggle_single_step()' in the script file.

In debugging mode, the dummy frame needed for javascript to be able to send scripts to Chime for immediate execution (see chiimmed.js) is large enough to be seen. (In lecture mode it is invisibly small). If immediate-mode script execution fails, you can view the source of the dummy frame to proofread it. Also, in debug mode, the immediate script button in the dummy frame is not hidden so that it can be clicked for test purposes.

Building Your Own Tutorial about the Molecule(s) of Your Choice

If you wish to build a linear Chime tutorial similar to this one, you can substitute your own content into Linear Control Structure version 2. Here are the recommended steps.
  1. Create a RasMol/Chime script in sections. This can be done in the following steps.

    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.

    2. Outline the presentation and divide it into major sections. Outline the presentation. Divide it into major sections each of which deals with a single topic or a few closely related topics. Note the five sections in this Protein Secondary Structure (ProtSecS) Tutorial. For review purposes (after seeing the entire script), the student or lecturer will be able to start playing the script at the beginning of any section. Each section should probably use a single PDB file. Most likely you will want at least several sections, and even in a very long tutorial, you probably won't need more than a dozen to twenty sections.

    3. Write a script for each section.. See the Guide to Script Creation in 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 controlling presentations. Most notable are clock-timed delay and move commands, and view-save, view-restore commands. Therefore it may be simplest to develop each script initially in RasMol, using pauses where later (in Chime) you will add smooth movements (such as rotations and zooms) or delays.

      Each of your section-scripts should be a self-contained module which will run from start to finish on its own. Therefore, each should start with a 'zap' command followed by a 'load' command to load the relevant PDB file. If more than one section uses the same PDB file, each section should load the file redundantly (at least during development). This makes it easy to start running any section at random. If the PDB file is very large and slow to load, and was used in a previous section, you can adjust the final scripts to inherit the PDB file when moving from one section to the next, loading it only when jumping into a middle section. The 5 sections in ProtSecS range in length from 75 to a little over 100 lines of commands each. Their filenames are given above. Yours can have any names you wish. Test: Make sure each script runs properly.

  2. Embed the section scripts into Linear Control Structure version 2. The steps for putting your section-scripts into LCS2 are as follows.

    1. Download ProtSecS and make a copy in a new folder. Instructions for downloading are provided. Make a new folder named according to the subject of your tutorial, and copy the ProtSecS files into it. Bookmark both the original ProtSecS (file index.htm) and your new copy separately. This will allow you to run either for comparison, or inspect the files in the original as needed. All operations below are, of course, to be done in the new folder, leaving the original ProtSecS folder intact.

    2. Revise the Table of Contents. Edit the file index.htm to reflect the contents of your tutorial. Please include an acknowledgement to Eric Martz with a link to Each section should be started with the javascript enter_section(n) where n is the number of the section.

    3. Revise startup_script creation. Edit the file startup.js, supplying the names of your section-script files. If you developed your scripts in RasMol, now is a good time to insert Chime-only commands (such as move and delay) to make full use of Chime. Use debug mode to help fine-tune your scripts. Test: At this point is should be possible to play the tutorial from start to finish, or beginning with any section, but the legends will be missing. It will not yet be possible to start in the middle or replay a section.

    4. Add legends. Each legend may consist of a color key plus some text (as in ProtSecS) or, if you wish, you can write html/javascript to create a different kind of legend. In the existing legend format, the color keys are one-cell tables generated by javascript functions in the file legend.js, Modify these functions to provide the color keys you need. The text for each legend is specified in the Chime-script by assigning quoted character strings to javascript variables. For example, the first legend is created with the following series of commands in the file alpha1.htm:
        javascript legend_key = "chon"
        javascript legend_text_centered = false
        javascript legend_text = "9-amino acid alpha helix.  "
        javascript legend_text += "Backbone atoms only (no sidechains)."
        javascript put_legend_globals()

      The function put_legend_globals() writes the legend html into the legend frame. Test: It should now be possible to play the tutorial from beginning to end with all legends being changed at the correct times. It will not yet be possible to replay sections.

    5. Specify sections to replay. Insert commands in your Chime-script files to specify which section to replay when the yellow button is pushed. For example, the command to set section 4 as the target of the replay button is javascript set_replay(4). You may not always want to change the replay target section immediately after the section begins. That would mean that pressing the replay button after the first image of the section would simply regenerate that image. Often it may make more sense to delay changing the replay target to the current section until after the second or third image into the section. You can watch the replay section monitor at the upper right in debug mode. Test: You should get an appropriate replay response from any point in your tutorial.

    6. Describe your design and methods. Replace the file design.htm with a new one which acknowledges and provides a link to the original Linear Control Structure version 2 and describes any new methods or design goals which you have introduced.

    7. What did I forget? I think you should be finished now, but I haven't tested these instructions yet. If I forgot something, please email me!


On-line manuals for RasMol and Chime, and various guides to script creation, will be found at the RasMol Home Page. In particular, note the guide to Creating Chime Web Pages. I have not found the on-line information on html and javascript to provide adequate introductions for beginners. Here is what I have been happy with, although of course these editions will be obsolete by early 1997.
  1. Lemay, Laura. Teach yourself web publishing with HTML 3.2 in 14 days, Publishing, Indianapolis IN US. 1,054 pages. Good overview of html, html serving, CGI, javascript, and java. Published June, 1996.
  2. Wagner, Richard, ed. Javascript unleashed, Publishing, Indianapolis IN US. Published October, 1996. Coverage up to Netscape 3.0. 869 pages plus CDROM. Thoroughly indexed.


Thanks to Tim Maffett of MDL Information Systems, Inc. for much helpful advice, for sharing pre-release versions of Chime, and for incorporating many of my suggestions into Chime. Of course none of this would have been possible without Roger Sayle's brilliant design of RasMol and its command/scripting language. Anne Simon (UMass, Amherst US) selected the content of ProtSecS for use in her Biology 100 class. The excellent Chime scripts by John Grant and George Helmkamp of the University of Kansas Medical Center provided the idea of opening a new window of fixed size 640x480. The creation of this script was supported in part by an instructional technology grant from the Office of the President of the University of Massachusetts.

Feedback to
Eric Martz.