Technical Information about FirstGlance in Jmol
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.
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
it have caused infinite reload loops in Safari.) Further information about
applet size control, when FGiJ is embedded in a table,
Three versions of FGiJ are provided. All three share common .js files
and some .htm files.
Which of the above versions is employed can be controlled with the
Advanced Options link at the main page, or with the
- fg.htm: No frames. This is the default version.
- 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).
- fge.htm: Embedded in a table.
This demonstrates how FGiJ can be surrounded by other content if desired.
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.
colors.js: definitions of colors.
config.js: variables specific to the configuration of the server.
contact.js: address for contacting the FirstGlance Development Team.
controls.js: writes the links and buttons that control the molecular
view into the upper left of the browser window.
enterurl.js: code for submitting a PDB code URL, or for uploading
a PDB file.
gallery.js: support for gallery.htm (displays of specific built-in PDB files)
help.js: all help texts displayed in the helpDiv (lower left panel).
- jcontrol.js: main variables and functions for molecular view
controls (owned by control.htm in framed version).
moldoc.js: generates applet in all versions of FGiJ. Also includes
jmolPickCallback() used for identifying clicked atoms, or for selecting
targets in Contacts.., or for hiding clicked moieties in
options.js: code for Advanced Options.
scripts.js: all scripts of Jmol commands (used by molecular view controls).
top.js: top level variables and functions (even in framed version) .
IMPLEMENTATION OF WINDOW SUB-AREAS
FGiJ consists of three rectangular sub-areas within the browser
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.
Jmol applet displaying the molecule (right)
Controls that change the molecular view (upper left)
Help (lower left)
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):
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).
The Jmol embed tag includes align='right'
The controls are in a scrollable division
The help is in a scrollable division named helpDiv
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.
The controls are inside the upper left table cell, and inside a
scrollable division within that cell.
The Jmol applet has its own cell (on the right, and which spans
two rows). This constrains the text below the applet to align with the
applet above. The embed tag does NOT use align='right' because this caused
the applet to be displayed partially outside and above the table cell (in
Firefox)! The applet is not in a division (within the table cell) because
this caused problems such as the applet displaying above the table cell
and partially outside the window in IE.
The help is inside a table cell, and inside a scrollable division
within that cell.
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).
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,
writeViewLink("cartoonSpt", "Cartoon", "cartoonHelp");
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.
- Sets some view-specific variables.
- Passes the help name to showHelp2(helpname).
- Sets the Ligands+ and Water toggle buttons up or down according to the new view.
- Records the new view name in currentView.
- Sends the command script to Jmol to produce the new view.
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,
writeToggleButton(ligandSpt, ligandOffSpt, "Ligands+", "down", "makeLigandsHelp()");
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.
- If the button went down, passes the help name to showHelp2(helpname).
(If the button went up, no help is displayed.)
- Changes the toggle button image to reflect its state.
- Records the new state in the boolean toggleIsDown.
- Sends the command script to Jmol to produce the new view.
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
Scripts that change the molecular view are sent to doMolviewSpt() for
pre-processing, while those that don't are sent directly to
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
(which is defined in the help frame, when frames are in use).
showHelp2() does the following:
- Nothing if the helpname is blank.
- Obtains the help HTML text corresponding to the helpname.
- Adds a link at the bottom to return to the Introductory help, when appropriate
- Writes the help according to whether or not it is a frame or a division.
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
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.
- 1PGB: single unnamed protein chain + water.
- 1EMB: single unnamed protein chain + water and CRO cromophore.
- 143D: single unnamed DNA chain with nothing else.
- 1D16: single unnamed DNA chain + water.
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.
Further, there is at least one PDB file that has both a named
protein chain, and an unnamed protein chain (4CPA).
In this case, FirstGlance's code will not support selecting the 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