Technical Information about FirstGlance in Jmol (FGiJ)


This document is provided for software developers who may be installing FGiJ into an existing website, or adding enhancements, and for those interested in the reasons for some design decisions made during the development of FGiJ.

APPLET SIZE

The size of the Jmol applet is specified in pixels. Using a percentage of the window for applet dimensions does not work in some common browsers. The applet dimensions (jmolWidth, jmolHeight) are calculated from the window dimensions in get_applet_dimensions() (thanks to Tim Driscoll for some of this code). If the window is resized after FGiJ is displayed, a manual reload/refresh will resize the applet accordingly. Automated methods of doing this were rejected as potentially annoying or problematic. (I have never been able to get onResize() to work well. In particular, my attempted uses of it have caused infinite reload loops in Safari.) Further information about applet size control, when FGiJ is embedded in a table, is below.

THREE VERSIONS

Three versions of FGiJ are provided. All three share common .js files and some .htm files.
  1. fg.htm: No frames. This is the default version.
  2. fgf.htm: Uses frames. (Discontinued in version 0.98.) Uniquely uses fs_left.htm, controls.htm, moldoc.htm, and blank.htm (as a temporary placeholder).
  3. fge.htm: Embedded in a table. This demonstrates how FGiJ can be surrounded by other content if desired.
Which of the above versions is employed can be controlled with the Advanced Options link at the main page, or with the hyperlink.

The main page, index.htm, controls which version of FGiJ is used by appending a query parameter "" (for frameless), "f" (for frames), or "e" (for embedded in table) when it loads gallery.htm. The query parameter is used in creating the links in gallery.htm that invoke FGiJ, so they call the appropriate file fg.htm, fgf.htm, or fge.htm.

JAVASCRIPT

IMPLEMENTATION OF WINDOW SUB-AREAS

FGiJ consists of three rectangular sub-areas within the browser window:
  1. Jmol applet displaying the molecule (right)
  2. Controls that change the molecular view (upper left)
  3. Help (lower left)
In the version that uses frames (fgf.htm not supported after version 0.97), each sub-area is a frame. Frames seem to work in all popular browsers. The mouse wheel scrolls text in the help frame in IE and Gecko browsers. A disadvantage is that the browser's Back button reverses the session history (hence the Close link in FGiJ's controls). Another disadvantage is that development and maintenance are complicated by frames.

In contrast, in the frameless version (which is the default, fg.htm), the mouse wheel does NOT scroll the help text in Gecko browsers. However, when a new window is opened for an FGiJ session, the browser's Back button remains greyed out, avoiding the confusion that use of the Back button causes in the framed version. Another problem that has not been solved is that when new text is displayed in the help division, the scroll position for the previous text remains, so you do not see the top of the new help without scrolling back up. [It appears that both of these problems may be solved by using a scrollable iframe instead of a scrollable division. This remains to be implemented and tested.]

In the version that does not use frames (fg.htm):
  1. The Jmol embed tag includes align='right'
  2. The controls are in a scrollable division
  3. The help is in a scrollable division named helpDiv
In the first implementation tried, the height of the scrollable help division was specified as a percentage value. When FGiJ first loaded, the "be patient" help is short, and the help division was the correct height. After a longer help text was loaded in a Gecko browser, the height of the help division would expand to more than twice that of the window (although still with a vertical scroll bar), and concomitantly the lower edge of the controls division went much too low. A similar problem was observed in IE with slightly different coding of FGiJ. This problem was solved by specifying the height of the scrollable help division in pixels. This height is calculated according to the browser window size (as is the Jmol applet size, see above).

When the frameless version of FGiJ is embedded in a portion of a browser window, its areas can be controlled by being within cells of a table, as demonstrated in fge.htm.

In the implementation (fge.htm) where FGiJ is embedded in a page with surrounding "outer" content, three table cells are used. Two of the table cells are for outer content, and the third contains FGiJ. FGiJ is configured as a table within this third cell which itself consists of three cells. This makes it relatively easy to transplant FGiJ as a self-contained block of code contained in this inner table. It is possible that both the controls division and help division can share a single left-side table cell. It is not clear whether this would waste a bit less space.

There are some variables (see examples at the top of fge.htm) that may control the portion of the window available to FGiJ. Based on the RCSB site, the assumption was made that FGiJ will be at the lower right of the window. Space not available to FGiJ at the left of the window is reserved with widthDecrement, and similarly for the top, heightDecrement. These are used to control the applet size in get_applet_dimensions(). These and other related variables may be seen at the top of fge.htm.

All versions use a small table within the controls area to group the buttons, and this table contains divisions (to avoid unwanted blank lines sometimes induced by using <br> tags).

VIEW-LINK MECHANISM

Clicking on one of a series of links (Secondary Structure, Cartoon, N->C Rainbow, Composition, etc.) changes the molecular view. The mechanism is as follows.

Links are written with a function call, for example, These calls are in controls.js. writeViewLink() stores the script and help variable names in the arrays viewLinkSptName[], linkHelp[], using an index incremented per call.

When the link is clicked, this function is called: where i is the index into the arrays of script and help names. doViewLink()

TOGGLE BUTTON MECHANISM

The control panel (upper left) contains several toggle buttons (Ligands+, Water, Slab, Background, Spin). The mechanism is as follows.

Buttons are written with a function call, for example, These calls are in controls.js. writeToggleButton() stores the parameters in the arrays toggleUpSpt[], toggleDownSpt[], toggleHelp[] using an index incremented per call. It also populates the state array toggleIsDown[], and the variables ligandsIndex, waterIndex, etc.

When a button is clicked, this function is called: where i is the index into the arrays. doToggleButton()

CHECKBOX SCRIPTS & SCRIPT PROCESSING MECHANISMS

Command scripts are sent to Jmol with scriptToJmol(script). However, usually some pre-processing is needed. For example, if some moieties are hidden, the postscript makeHideSpt() needs to be added to any scripts that render the molecule. Also, certain state variable may need to be changed. For example, the Composition view unconditionally depresses the water and ligands+ buttons.

Script pre-processing is handled by doToggleButton() and doViewLink() for those cases. Other scripts can be divided into those that change the the molecular view, and those that don't. Examples of the latter are scripts sent by the Zoom buttons, or the checkboxes to show the axes, unit cell, or boundbox.

Scripts that change the molecular view are sent to doMolviewSpt() for pre-processing, while those that don't are sent directly to scriptToJmol().

HELP DISPLAY MECHANISM

The contents of the help panel are changed with a call passing the name of the help, for example This function calls showHelp2() (which is defined in the help frame, when frames are in use). showHelp2() does the following:

"LIGANDS+", "NON-STANDARD RESIDUES": DEFINITIONS

Atom-set terms used in FirstGlance are defined in notes.htm, which includes links to more specialized documents where relevant.


MECHANISM FOR SELECTION OF UNNAMED CHAINS BY CLICKING

Chains are given single-character names in most PDB files. However, some files have only a single chain, and in these cases, the single chain is not always named. Examples: FirstGlance can select a named chain by clicking on it. This select-by-clicking mechanism is used in two interfaces: to select a target in Contacts.., and in the Hide.. interface. The pickCallback mechanism is used to report from Jmol to javascript the identity of the atom clicked (see code in moldoc.js). The selection dialog has radio buttons to specify whether a chain, a residue or group, or an atom will be selected on each click. When chains are specified, and the report includes a chain name, this mechanism works as intended.

However, the above mechanism fails when the chain has no name. In that case, the pickCallback report includes the residue name and number, but lacks any chain information. Therefore, when chains are specified for selection, and the clicked atom has no chain information, the residue name is examined. If the residue is one of the 20 standard amino acids, or 5 standard nucleotides, all protein or all nucleic acid is selected, respectively, on the assumption that this is a single-chain PDB file. This mechanism will still fail when a non-standard residue is clicked within an unnamed chain. If chains are specified for selection, and the residue clicked lacks a chain name, and is not a standard amino acid nor nucleotide, then FirstGlance alerts the user to change the radio buttons to specify residues/groups for selection. This alert is issued only once per session.

Further limitations of the select-by-clicking mechanism are described in

Feedback to