Instructions for authoring molecular structure tutorials in the Jmol Tutorial-Authoring Template (JTAT). Caution: These instructions for authoring tutorials in JTAT have not been updated since the 2010 version. This old version applies for the most part, but some changes are not yet documented here. Updating these instructions is planned soon. If you have questions or suggestions for improving this document, don't hesitate to contact me (emartz@microbio.umass.edu). -Eric Martz, September, 2008 I. Proteopedia vs. JTAT Introduction & Overview: JTAT vs. Proteopedia Getting started: Use Proteopedia.Org! II. JTAT Background & Preparation Jmol java applet and application What skills do you need to author a tutorial in JTAT? Download and explore the molecular models (PDB files) you need. Get familiar with the JTAT Demonstration Tutorial. III. Setting Up A New JTAT Tutorial Organization of files and folders in JTAT. Start a new tutorial: Copy the Template. Files needed in each chapter. IV. Authoring your New JTAT Tutorial Your Title & Contents Editing Javascript Files Install a Molecular View in Contents: setupButton(...). Set the desired molecular orientation and zoom Describe Your First Molecular View HTML Quick Reference   Finish Your Contents. Add Chapters with More Views & Descriptions Fill in the Window Title and Footer Information Deploy Your Completed Tutorial. V. Scripting Molecular Views (Scenes) Scripting molecular views. Scripting in Proteopedia. Scripting in FirstGlance in Jmol. Direct Scripting. Troubleshooting Scripts That Don't Work. VI. Color Schemes and Color Keys The DRuMS Standard Color Schemes. How to Color Your Molecules with DRuMS How to Make Color Keys JTAT's functions for standard color keys. Color key text with HTML style class spans. Colored Text HTML Quick Reference   Color key text in non-standard colors and the standard color key font: the ckey() function. Color key text in non-standard colors and the default font: the HTML font tag. VII. Optional Tutorial Configuration Settings. Convenience Settings While Authoring Optional Tutorial Configuration Settings. VIII. Checkboxes, etc. Checkboxes That Modify the Molecular View. IX. Animations and Movies Animations vs. Movies: Which to Use? Making and Using Animations Making and Using Movies

Jmol is a powerful, free program that displays 3D molecular models. The models, displayed and colored as desired, can be rotated and zoomed interactively with the mouse. The tutorial-authoring tools discussed here, Proteopedia and JTAT, use Jmol (in its java applet form) within a web browser. Tutorials may be made freely available on-line, or, in the case of JTAT, can also be projected from a local (optionally private) copy.

The easiest and quickest way to create a molecular structure tutorial in Jmol is with Proteopedia.Org, an innovative free website created in 2007 by Sussman, Prilusky, and Hodis. Its Scene Authoring Tool makes it quite easy to create customized molecular views or scenes, and its wiki format makes it easy to describe your scenes with accompanying text. "Green links" placed in the text show your views. Examples of such tutorials are linked to Proteopedia's main page.

Proteopedia limits what you can do, to some degree, which contributes to its ease of use. JTAT offers greater control, and offers several features and amenities to enhance your tutorials, but these come at the price of requiring additional skills and time during tutorial authoring.

Luckily, you don't have to decide in advance which to use. We recommend that you start making a tutorial in Proteopedia. Then, if it seems worthwhile, you can easily move the scenes and text from Proteopedia into JTAT, to get a feel for what is involved. In fact, we recommend using Proteopedia to author your molecular scenes, even when you plan to deliver your tutorial in JTAT.

Both Proteopedia and JTAT tutorials operate in standard web browsers, such as Firefox, Internet Explorer, and Safari (Windows, Mac OS X, or linux). Both support multiple molecules in one page/chapter, and both have toggles for graphics quality. They differ in the following features:

Proteopedia and JTAT enable authors of macromolecular structure tutorials to concentrate on the scientific content, rather than on web page programming. Authors choose molecules, design molecular views, and explain them. JTAT provides a template or "shell" that sets up the molecular display, a scrolling panel of view buttons and descriptions, ready-made style sheets, and many other amenities that improve usability and make your tutorials look classy. Typically, most molecular views show a single molecule, but JTAT can show two, three, or four molecules for side by side comparisons. The best way to see JTAT's range of capabilities is to run through the JTAT Demonstration Tutorial.

JTAT displays molecules in a web browser, using the Jmol java applet, a free, open-source molecular display program that requires no installation. JTAT tutorials work from disk files (off line) or from servers (on line). They work in Windows (in Internet Explorer, Mozilla Firefox), in Mac OS X (in Safari or Firefox), and in linux (in Firefox).

In brief, after getting familiar with these instructions, you download JTAT. It includes an empty template, which is a working tutorial, except without any molecular content. You view the template in your favorite web browser. Then, following the instructions below, you insert molecular content into the template. The content consists primarily of customized molecular views, with descriptions of the views, which include color keys: text colored to match the colors of the molecule. After each change to your tutorial's content, you reload it in the browser to see the change. When you're finished, you can put the tutorial on-line for use by your students, or project it from local files (or on-line) to illustrate a lecture.

Proteopedia.Org is the easiest and quickest way to create an on-line macromolecular structure tutorial. A detailed comparison with JTAT is in the table above, and succinct comparisons with other tutorial-authoring systems are on JTAT's main page.

We suggest that you begin by creating, in Proteopedia, a few scenes (views) of the molecule(s) that will feature in your tutorial, and also that you begin writing their descriptions there. You will need to apply for an account at Proteopedia.Org, which requires that you use your real name. Click the log in/request account link at the upper right at Proteopedia.Org.

Proteopedia's Scene Authoring Tool is by far the easiest way to create a customized view of a macromolecule. You may decide that completing your tutorial in Proteopedia, and leaving it there on-line, meets your needs quite well.

Protected Pages. Proteopedia is a wiki. Unlike most wiki's, however, you can protect your tutorial in Proteopedia from changes by others. (By contributing your tutorial to Proteopedia, you give others permission to copy your tutorial, and modify and adapt the copy, but your original will remain intact.) Instructions for creating protected pages are linked to Proteopedia's main page, under What Can Proteopedia Do For Me?.

Scenes and scene descriptions that you create in Proteopedia can readily be installed in JTAT. Indeed, Proteopedia is the easiest way to create macromolecular scenes for JTAT, and the way that we recommend. Other methods are described below.

Jmol requires java. Jmol comes in two forms, both of which have the same display capabilities and command language. Both require java in order to operate. Java is free, and cross-platform; that is, it enables programs written in java to run identically on Windows, Apple Macs, or linux, without needing a different implementation for each platform. Apple Mac OSX comes with java, and Apple Software Updates keep it up to date. Windows comes without java, but java can be installed at no cost, quickly and smoothly from java.com. Java is used by many other programs besides Jmol.

Jmol Applet. JTAT uses the applet form of Jmol because this is the form that operates within a web browser. Delivering tutorials to users on the web has many advantages. The browser makes the display, layout formatting, and organization of text relatively easy. Delivering tutorials in browsers makes them highly accessible. When a web surfer visits a site that uses Jmol, Jmol is sent to the user's browser silently, quickly, and automatically. This means that, aside from having to install java on Windows systems, nothing needs to be installed in order to use a Jmol applet-based tutorial. When you download JTAT, the Jmol applet is included.

Web browsers contain a versatile programming language called javascript (not to be confused with java). This makes it possible to have menus, buttons, and links that control the molecular view within the applet. It also enables the applet to inform the browser about actions taken by the user, such as what atom has been clicked. JTAT uses javascript extensively, but you will need to learn hardly any javascript in order to use JTAT to author a tutorial.

Jmol Application. The Jmol application is a stand-alone program (as are RasMol, PyMol, and many other popular molecular visualization programs). Unlike the Jmol applet, it runs independently of, and has nothing to do with, web browsers. And unlike RasMol and PyMol, which need implementations (source code compilations) specific for each computer platform, a single Jmol program runs identically (with the help of java) on Windows, Apple Macs, and linux. Optionally, the application can be used when you are developing molecular view scripts for JTAT. Instructions are provided.

Biochemistry. We assume that you know about, or are learning about, a molecular structure -- and that you wish to present a series of informative views of this molecule, explaining its salient structural features, and how they support its function.

Text Editing. First, you'll need to be able to edit plain text files, using a text editing program. Plain text editors include Notepad, a simple but adequate text editor that comes with Windows, and TextWrangler or BBEdit, superb text editors for Macs. You can also use word processors (such as Wordpad in Windows, Textedit or iWork Pages on Macs, or Microsoft Word) but then you must be careful to save the file as plain ("ASCII" or "DOS") text. If you inadvertantly save it as a document file, it won't work -- but then you can simply re-save it as plain text.

You'll need to edit plain text files that contain the text descriptions for your molecular views, and the Jmol script (.spt) files that specify those views.

Windows Notepad: Start, (All) Programs, Accessories, Notepad.

Mac OSX: TextWrangler is an excellent and free text editor for Mac OS X. BBEdit, from the same company, is the supreme Mac text editor (30 day free demo). Get them from barebonessoftware.com

HTML (HyperText Markup Language). Second, you'll need to be familiar with just a little HTML, in order to color your text to match colors in the molecular view, and to insert links and images into your tutorials.

Jmol scripting. Third, you'll need some familiarity with the Jmol molecular view command scripting language. This is a superset of the RasMol and Chime command languages. Command scripts, or scripts for short, will be saved in plain text files whose names end ".spt".

Gather the PDB codes for the molecular models that you want to display in your tutorial. Good places to search for published PDB files are listed in the syllabus for the most recent Martz Workshop.

Download the PDB files themselves. After you set up the directory for your new tutorial, these files can be put in the directory jtat/tutorial_name/molecules4all. ("molecules4all" means "molecules for all chapters" -- you may use a given PDB file in more than one chapter, or not, as needed.) Make sure that the saved filenames are all lower case (see below) and end in ".pdb".

You can download any molecular model that you see in Jmol (or Chime). Click on the "Jmol" frank in the lower right corner beneath the molecule, to open Jmol's menu. Click the top item on the menu, and then the last item on the submenu that opens. If the PDB file appears in the browser as text, use the browser's File, Save As, and save the file as plain text with a lower case filename ending with ".pdb".

Plan what you want to show and explain in your tutorial. The best place to start exploring a molecule is Proteopedia.Org: it shows the name of the molecule, the reference to the original publication, the abstract from the original publication, the resolution of the model, the locations and full names of ligands and functional sites, and more. From within Proteopedia, click the link (beneath the molecule) to FirstGlance in Jmol for further exploration.

The material that follows will make a lot more sense if you get familiar with the JTAT Demonstration Tutorial. First, you need to be familiar with how the Demo looks in a browser. This will help you understand what we mean below by Table of Contents and Chapter, molecular views, etc. Then, as you read below, be sure to look at the folders and files that make up jtat/jtatdemo. This will give you a concrete example to see how those folders and files support the tutorial as it appears in a browser.

It is very important that you understand the organization of files and folders within JTAT. This will enable you to avoid inadvertently breaking JTAT, and enable you to place your new tutorials and alterations correctly. It will greatly facilitate moving your tutorials to new versions of JTAT, should new versions become available.

The jtat folder. All of JTAT is contained in a folder (directory) we'll call jtat. When you download JTAT, the main folder will include its release date in its name. For example, jtat_2008_02_15 would signify a release date of 15 February (02), 2008. It is best to leave the release date in the folder name because you may well end up with several versions of JTAT side by side (see next paragraph), in which case leaving the release dates of each in their folder names will be very helpful. The release date of each version of JTAT is displayed at the bottom of the control panel in every tutorial. Below, we'll refer to the folder generically as jtat.

JTAT versions. You can have multiple versions of JTAT side by side, as long as the main jtat folder has a distinct name for each version. In some cases, it might be simpler to leave a well-functioning tutorial in an older version, particularly when it would need extensive revisions to make it compatible with a newer version of JTAT.

Tutorial folders. Multiple tutorials can be contained in jtat, each in its own folder. For example, the JTAT Demonstration Tutorial is in a folder named jtat/jtatdemo. Were you to create a new tutorial on acetylcholinesterase, an appropriate folder name for it would be jtat/acetylcholinesterase. This folder will contain all text, molecular view scripts, images, and other components that are specific to this tutorial.

All tutorials in jtat share the JTAT shell, that is, the code that sets up and operates the tutorial. This code is in a set of standard folders that are shared in common among all tutorials, and are named as follows:

You will not need to touch anything in these folders. Note that the names of most begin with an underscore.
• jtat/_cssutil contains cascading style sheets (*.css).
• jtat/_docs contains the JTAT documentation (mostly *.htm).
• jtat/_drums contains scripts (*.spt) for the DRuMS Standard Color Schemes, as well as drums.css for coloring matching text color keys.
• jtat/_jsutil contains javascript (*.js).
• jtat/_imgutil contains images (*.jpg, *.gif, *.png).
• jtat/_sptutil contains Jmol command scripts (*.spt).


• jtat/jtatdemo contains the JTAT Demonstration Tutorial.

Each tutorial that you create will add another folder to the above list.

In addition to the above folders, the following are the only files that should be present in jtat:

• jtat/index.htm is where you start your browser. Typically, this file would contain links to each of your tutorials, and a link to the JTAT Documentation (jtat/_docs/index.htm). You should edit this file to provide the appearance and content you desire, including links to all tutorials in this folder.
• jtat/Jmol.js is javascript that supports the Jmol applet. The version of Jmol.js must match the version of the applet. DO NOT EDIT THIS FILE.
• jtat/jmolApplet0.jar and jmolApplet0_*.jar files (where * represents various words) make up the Jmol applet. DO NOT TOUCH THESE FILES.

JTAT files you can edit. For the most part, you should not alter the jtat files or folders that are outside your tutorial's folder. There are a few exceptions listed below. However, most authors will never need to touch any of these files (except for index.htm).

• jtat/index.htm can be edited to have any style and contents that you like. Typically, this file would contain links to each of your tutorials, and a link to the JTAT Documentation (jtat/_docs/index.htm).
• jtat/_jsutil/config.js, jtat/_jsutil/config2.js may be edited judiciously to change settings that will affect all tutorials in the current jtat folder. If you wish to change one of these settings in one or a subset of the tutorials in the current jtat folder, you should change or add these settings in the relevant file(s) in jtat/tutorial_name/js4all.
• jtat/_cssutil files may be edited judiciously to change the styles of elements in all the tutorials in the current jtat folder. Styles specific to one or a subset of the tutorials belong in jtat/tutorial_name/css4all.
• jtat/_imgutil is a place to add any images that you plan to use in more than one of your tutorials. Images specific to one tutorial belong in jtat/tutorial_name/images4all.
• jtat/_sptutil is a place to add any Jmol command scripts that you plan to use in more than one of your tutorials. Scripts specific to one tutorial belong in jtat/tutorial_name/spts4all.

Copy the Template. To create a new tutorial, copy (duplicate) the folder named template (in the jtat folder), including all the folders and files it contains. Now rename Copy of template to, for example, acetylcholinesterase (or whatever is the topic of your planned tutorial). Below, we'll refer to it generically as tutorial_name.

Lower case for all folder and file names! Nearly all file and folder names in JTAT are entirely in lower case letters. (The exceptions are Jmol.js and jmolApplet*.jar.) We strongly recommend that you use only lower case letters (a, b, c, ...) and no upper case letters (NOT A, B, C, ...) in file and folder names. Case mismatches in file or folder references are harmless in Windows and Macs, but when your tutorial is moved to a server, they can be tedious to fix!

View Your New Tutorial. There are several ways to set up a convenient way to view your new tutorial. Use whichever you like.

Note that Firefox is recommended (in both Windows and Macs) for developing and testing JTAT tutorials (see below).

Files and folders making up a tutorial. Your new tutorial folder (we'll call it tutorial_name) should contain the following:

• jtat/tutorial_name/index.htm This is the page you open in a browser to start the tutorial. It can contain whatever you wish, such as an introduction to your tutorial, or nothing. If empty, it can simply redirect the browser to jtat/tutorial_name/contents/contents.htm, the Table of Contents for your tutorial. (A file named jtat/tutorial_name/redirect.htm is provided. It can be copied to jtat/tutorial_name/index.htm if you want to start directly at the tutorial's Contents page.)
• jtat/tutorial_name/contents One folder for a Table of Contents (optional -- if your tutorial has only one chapter, then you don't need Contents).
• jtat/tutorial_name/chapter01 One folder for each chapter in this tutorial. You can make as many chapters as you wish by copying and renaming jtat/template/chapter01 for each new chapter. Chapter folders can be named in any way you like. In the JTAT Demo Tutorial, I began the name of each chapter folder with ch_, e.g. ch_view1, ch_movie, ch_spin, etc.
• jtat/tutorial_name/css4all, images4all, js4all, molecules4all, scripts4all These folders contain cascading style sheets, image files, javascript files, molecular atomic coordinate files (such as PDB files), and Jmol script files, respectively. Only files specific to the content of this tutorial belong in these folders. Files shared between two or more tutorials belong in the corresponding folders in jtat (see list above). Some of these folders come with essential content already present (css4all, js4all), some are empty (images4all, molecules4all), and scripts4all has some sample scripts that are nonessential.

If you haven't already done so, put the PDB files you need in jtat/tutorial_name/molecules4all.

Before starting to add content to your new tutorial, it will be helpful to understand the files that will make up each chapter. The folder for each chapter (we'll call it chapter_name) needs to contain the following files. The contents folder contains similar files as indicated.

• jtat/tutorial_name/chapter_name/chapter.htm (or jtat/tutorial_name/contents/contents.htm). The names and contents of these files should not be changed.


• jtat/tutorial_name/chapter_name/chapter.js (or jtat/tutorial_name/contents/contents.js). The names of these files should not be changed. However, this is where you provide the text of a chapter, including descriptions of each molecular view, color keys, and details.


• jtat/tutorial_name/chapter_name/initial-view.spt is required. It is the Jmol script file that specifies the initial view for a chapter (or contents). Usually this is View 1, plus some additional commands that display only when the chapter is first entered. So typically, this script calls view01.spt, but adds a few things to it. For examples, see the initial-view.spt files in jtat/jtatdemo. JTAT expects and calls this script automatically; you do not need to refer to it in chapter.js.


• jtat/tutorial_name/chapter_name/view01.spt is the script that specifies the molecular View 1 in this chapter. You can name this file anything as long as it ends in .spt. Its name must be specified both in initial-view.spt, and in chapter.js for the first View button.


• jtat/tutorial_name/chapter_name/view02.spt, view03.spt, and so forth, are the scripts for each molecular view in this chapter. Again, their filenames can be anything you wish, as long as each ends in .spt, and is specified correctly for its corresponding view button in chapter.js.


• Additional files that you should add to jtat/tutorial_name/chapter_name/ would include any images or utility scripts that are unique to this chapter. Images, scripts, style sheets, etc. that are shared by more than one chapter belong in the jtat/tutorial_name folders images4all, scripts4all, etc. (see above).

This section assumes that you have already followed the instructions under How to Start a New Tutorial.

Title. When you first view your copy of the template in your browser, at the top, you'll see someting like Put Tutorial Title Here. Let's do that. This may be the first time you will be editing a .js (javascript) file, so in the next section, we discuss some technical problems that might occur, and how to find and fix them. It would be a good idea to read Editing Javascript Files before continuing with this section.

In the file jtat/tutorial_name/contents/contents.js, you will find a line something like this:

var chapterTitle = '[Put Tutorial Title Here]';

Use your text editor to replace the placeholder text with the real title of your tutorial. For example, you might change the above line to this:

var chapterTitle = 'Acetylcholinesterase';

Now, save the changed file (as plain text), and then reload your tutorial in your browser, and you should see your real title in the browser.

If you do not see the the title that you typed into the file contents.js, please read the following section, which describes troubleshooting.

Adding textual content to your tutorial is largely a process of repeating the above cycle: change a javascript text variable, save the .js file, reload the page in your browser, and troubleshoot if anything goes wrong.

Do you need a Contents page in your tutorial? If your tutorial will have more than one chapter, you should use a Contents page (which serves as a Table of Contents) that provides a list of your chapter titles, and a link to enter each chapter.

If you will have only one chapter, you may prefer to skip the Contents page. In order to do that, in the file jtat/tutorial_title/index.htm, change this line

document.location.href = "contents/contents.htm";

to this line

document.location.href = "chapter01/chapter.htm";

Of course, if you renamed the folder chapter01 to something else, you'll need to use that name in the above line.

If you decide you don't need a Contents page, because you plan to have only one Chapter, then you should put your first molecular scene, and its description, in the file jtat/tutorial_name/chapter01/chapter.js. If later you decide to add additional chapters, and then you would like to have a Contents page, simply reverse the change described above that skips the contents, and put a molecular view, and links to your chapters, in the file jtat/tutorial_name/contents/contents.js.

Editing javascript files. The textual content in a JTAT tutorial is stored in javascript files, whose names end in .js. The text itself is stored in various javascript text string variables. For example, in the file jtat/tutorial_name/contents/contents.js you will find:

var chapterTitle = '[Put Tutorial Title Here]';

The above line defines the javascript variable chapterTitle to contain the text you see in quotation marks. You simply edit the text between the quotation marks to put in a real title. For example

var chapterTitle = 'Acetylcholinesterase';

The tricky part is to avoid inadvertantly changing the parts shown in red here:

var chapterTitle = 'Acetylcholinesterase';

Those red parts are absolutely required, unchanged. For example, none of the following will work. (Portions following // are comments, that is, they are ignored by javascript.)

ar chapterTitle = 'Acetylcholinesterase'; // "v" missing from "var"
var chapterTitl = 'Acetylcholinesterase'; // "e" missing from chapterTitle
var chapterTitle = 'Acetylcholinesterase; // closing quote mark missing

So, the trick is to pay careful attention to leaving the javascript syntax intact. (The word var is not always needed. It depends on issues we don't need to get into here. If var is present, leave it; if not, don't add it.)

It is highly recommended that you make one change at a time to a javascript file, and then reload the relevant page of your tutorial in the browser to confirm that all is well. When you have made many changes before testing the result (by reloading in the browser), it becomes much harder to find the problem. But what if you do accidentally damage the javascript?

Troubleshooting: The Javascript Console. Sooner or later you will accidentally damage the syntax of the javascript. It happens to the best of us -- fairly often! The symptom will typically be that parts of the page will fail to appear in the web browser.

The Firefox web browser is particularly good at telling you exactly where the problem is. Therefore, we highly recommend that you use Firefox (on both Windows and Macs) for testing JTAT tutorials during development.

Firefox locates broken javascript in its Error Console. This is a special window that is opened from Firefox's Tools menu. So, whenever you suspect a problem with javascript, check the Error Console. To make sure that only current errors are shown, press the Clear button in the Error Console, reload your page in the browser, and then check the Error Console again.

Double vs. single quotes . It doesn't matter whether a text string is double or single quoted, provided the opening quote and the closing quote are matched. These two are valid and equivalent:

var chapterTitle = 'Acetylcholinesterase'; // VALID
var chapterTitle = "Acetylcholinesterase"; // VALID

A common pitfall is to include quoted material within a quoted string. This is best accomplished by using double vs. single quotes. For example, suppose we want the word red to appear in color, using an HTML font color tag. The following will not work because the opening quote around red (marked with ^) inadvertantly closes the whole text string variable.

var chapterTitle = "A <font color="red">Red</font> Molecule"; // INVALID
                                 /^\

The solution is to use double quotes within single quotes (or vice versa):

var chapterTitle = 'A <font color="red">Red</font> Molecule'; // VALID
var chapterTitle = "A <font color='red'>Red</font> Molecule"; // VALID

But you have to be careful to match each pair!

var chapterTitle = 'A <font color="red">Red</font> Molecule"; // INVALID
                                                          /^\

Apostrophes and escaping quotes. Single quotes are often used around the main text, so you can double-quote items within the text, such as red font coloring. In such cases, you cannot use a single quotation mark as an apostrophe, because it prematurely terminates the quoted string:

var chapterTitle = 'An Amino Acid's <font color="red">Mutation</font>'; // INVALID
                                /^\

One solution, of course, is to use double quotes around the main text. However, in the example above, we need double quotes within the text for red . So the solution is to mark the apostrophe as being part of the text, not the end of it. This is done by preceding it with a backslash (\), which is called escaping it:

var chapterTitle = 'An Amino Acid\'s <font color="red">Mutation</font>'; // VALID

Literal quotes. If you want literal quotation marks to appear around a word or phrase in the text, use HTML quotation tags:

var chapterTitle = 'A <q>Quoted</q> Word'; // VALID

If the text is long (multiple lines), there are two ways to handle it.

chapterIntro =
'<p> \n\
Here is some text that is long enough that we prefer to  \n\
break it into several lines. Also, it makes the \n\
javascript more readable to put the paragraph tags \n\
on separate lines, as is done here. \n\
</p> \n\
';

In the above method, leaving the \n\ off the end of a line causes a fatal javascript error (meaning simply that the javascript cannot be interpreted, and will fail to display correctly). Another error that is nearly impossible to find is inadvertantly putting a space after \n\ . Firefox's Error Console will report unterminated string literal. The Error Console will tell you the line number where the offending string begins. Check the end of each line carefully looking for an (invisible) space.

The second method is like this:

chapterIntro =
"<p> " +
"Here is some text that is long enough that we prefer to  " +
"break it into several lines. Also, it makes the " +
"javascript more readable to put the paragraph tags " +
"on separate lines, as is done here. " +
"</p> ";

The above two methods are equally good.

Empty string variables. Sometimes you want no text in a certain location. For example, you might not need a subtitle. In such cases, it may be crucial that the subtitle variable be defined but its value be empty:

var chapterSubtitle = ''; // VALID: EMPTY (BLANK)

Deleting the above line would leave the variable chapterSubtitle undefined, and could cause a fatal javascript error.

The following steps will install a molecular view on your Contents page.

1. Make sure the PDB file for your view is present in jtat/tutorial_name/molecules4all as explained above.


2. Near the end of the file jtat/tutorial_name/contents/contents.js you will find a javascript function setupButton(...). This is where you specify the molecular view for the Contents page. Even though there will be no molecular view buttons in the Contents page, the molecular view is specified by using this function.


3. Leave the number of molecules specified as 1 in the first parameter of setupButton(...). (JTAT supports having more than one molecule, in more than one Jmol, in the single "view" in Contents. However, even if you think that would be useful in your tutorial, for now, let's keep it simple by showing only one molecule in one Jmol. You could try multiple molecules later.)


4. Put the PDB filename in the second parameter, replacing the "xxxx" in "../molecule4all/xxxx.pdb". If you want to look at an example, see jtat/jtatdemo/contents/contents.js. Now reload your tutorial in the browser, and you should see the molecule.


5. At this stage, the molecular view will be a default view specified in jtat/tutorial_name/contents/initial-view.spt. To customize the view, you will need to change the contents of this script file. See the next section below to set the desired orientation and zoom. To customize the rendering and coloring, see Scripting.


6. The third parameter of setupButton(...) is 'script initial-view.spt' (quotes required). This specifies the script that will be run to produce the desired molecular view. Don't change this parameter. (You will change the contents of the script file, but not its name.)


7. By default, the background color is specified as black in the fourth parameter of setupButton(...), blackBackground (without quotes). Black is the default because generally most molecular views show up better on black than on white, especially when projected. However, some show up better on white, and you may change this to whiteBackground if you wish. Incidentally, backgroundWhite and backgroundBlack also work.


The background color for text (in the control panel on the right) will automatically be the same as that of the molecular view. For more about this, please see the chapter on Background Colors in the JTAT Demonstration Tutorial.


8. By default, tbe fifth and last parameter in setupButton(...) is spinningStart. This need not be changed for the Contents page, but when you get to chapters with multiple views, the explanation below will be useful.


• spinningStart: When the page loads, this view will spin. After displaying one or more other views in the page, if you return to this view later (without reloading the page), this view will adopt spinningSame mode (see next item).


• spinningSame: When displayed or redisplayed, this view will inherit whether or not to be spinning from the previous view. If the previous view was spinning, this view will start out spinning; and vice versa. It does not matter whether the previous view started out spinning; what matters is whether it was spinning when the this view was requested. In other words, if the user clicked the Spin Toggle button, whatever mode the previous view was in is inherited by this view.


• spinningOn: When displayed or redisplayed, this view will always start out spinning.


• spinningOff: When displayed or redisplayed, this view will always start out not spinning.

Please also see the chapter on Spin Control in the JTAT Demonstration Tutorial.

Jmol makes it easy to specify the initial orientation and zoom for any molecular view. This can be done before you have customized the molecular rendering and coloring, afterwards, or again at any time you decide to change it. Here is how.

(This section makes some references to Jmol commands and command scripts. You may want to read the upcoming section on Scripting Molecular Views before proceeding.)

1. Use the mouse to rotate and zoom the molecule to the orientation and size that you want. Zooming can be done with the mouse wheel, unless you are using Safari. Before moving the mouse wheel, click on the molecule to focus Jmol. If you want finer control, or if you are using Safari, hold down the shift key while dragging the mouse up or down in Jmol.
2. Click on the gray Jmol, to the lower right of the molecule, to open Jmol's Main menu. At Show, click on Orientation. The Jmol console will appear, and it will contain something like this:

moveto /* time, axisAngle */ 1.0 { -512 593 -622 120.03}
/* zoom, translation */  111.93 0.0 0.0
/* center, rotationRadius */ {27.204605 41.80329 28.43788} 45.783455
/* navigation center, translation, depth */ {0.0 0.0 0.0} -49.80277 -41.18717 50.0;
#OR
#Follows Z-Y-Z convention for Euler angles
reset;center {27.204605 41.80329 28.43788}; rotate z -87.96; rotate y 85.43; rotate z -6.31; zoom 111.93; set rotationRadius 45.78;
Jmol script terminated

3. Copy the desired line from the Show Orientation report. On Mac OS X, you will need to block, then drag and drop because (at present) you can't copy from the Jmol console. Which line?
• If you want the molecule to simply appear at the outset in the specified orientation and zoom, copy the line that begins reset stopping just before Jmol script terminated.
• Alternatively, you may specify that the molecule roll and zoom gracefully into its desired orientation, over a few seconds, just like in the initial view of the Contents of the JTAT Demonstration Tutorial. In that case, copy the line that begins moveto, stopping just before the #OR.
4. Paste the reset/moveto commands into the initial-view.spt script file for the contents or chapter in question. It should be near the end. (If a moveto command was already there, replace it.)
5. Uncomment the commands provided in the initial-view.spt template file that put the molecule in a good starting position to roll and zoom into view. These are about three command lines that include zoom 15, which reduces the molecule to 15% of full size before it starts zooming into view.
6. If you are using a moveto command, change the first number after the word moveto to the number of seconds over which you want the action to occur. Try different values to see what you like. Typically, about 2 seconds is good.
7. Try reloading the contents or chapter containing your new orientation/zoom script (or pressing the View 1 button) to see the result.
8. Inherited Orientation/Zoom. In chapters with multiple views of the same molecule, normally each View button will leave the prior orientation/zoom unchanged. This means the user can rotate the molecule, and zoom it, and then see different views in that user-set orientation and zoom.
9. Specified Orientation/Zoom. Alternatively, if you want to force the view into a particular orientation/zoom, you can add the reset or moveto command into the viewNN.spt file. If this file contains a state script, it will already include orientation and zoom. However, if you want to change only the orientation and zoom (but not the colors and representations) you can simply paste another reset or moveto command into the end of the script file.
10. Repeat this procedure later on for each new view, as you develop or polish it. You can always replace any existing orientation/zoom with a new one.

Describing the Molecular View in the Contents page. You probably wish to provide a description of the molecular view you have now installed in the Table of Contents for your new tutorial. In the file jtat/tutorial_name/contents/contents.js, you will find the javascript string variable chapterIntro. This is a good place to describe the molecular view. If you wish to provide additional details about the view, you may put the topic of these details in topContentsDetailsTitle and the details themselves in topContentsDetailsText.

Don't forget to make one small change at a time, and to reload your browser to see the changes (or troubleshoot any errors) after each change!

Using HTML in your tutorial text. By "text" in your tutorials, we mean the text you type into the javascript string variables for text that will be displayed in your tutorial, such as titles, subtitles, chapter links, text below chapter links, introductions, molecular view descriptions, details titles, details, and conclusions. If you wish to make some of your text strings, or portions of text javascript strings, larger, boldface*, italics, colored,

and so forth, you can do so by including HTML tags. JTAT includes a handy

  HTML Quick Reference Page  

from which you can conveniently copy and paste the HTML tags you need. If you need something more advanced, just search for "html" and what you need with Google.

Finishing the text in your Contents page. Now that you know how to put text into javascript string variables in the file jtat/tutorial_name/contents/contents.js, you can proceed finish up the text in your Contents page. Examining the variables in contents.js will show you where to put the subtitle, introduction to your tutorial, the name of your first chapter, any details you wish to provide, and the conclusion. All of these are optional except for the name of your first chapter. Those you don't need can be set to empty (blank) strings.

The Next Button. The usual way to enter a Chapter from the Contents is to click the link for the chapter's title. But there is also a Next button near the bottom of the Contents. In jtat/tutorial_name/contents/contents.js is a variable nextChapterButtonGoesTo, which comes set to go to chapter01. If you gave the folder for your first chapter a different name, you'll have to change chapter01 to the new folder name to make the Next button work.

Now you have created your first molecular view, in your Contents page, and described it. (If you still need to customize the molecular view, please see Scripting.) Completing your tutorial consists largely of adding one or more chapters, creating additional molecular views, and describing them.

Create Your First Chapter. The folder for your first chapter is already present: jtat/tutorial_name/chapter01. In order to add molecular views and text, you edit the file jtat/tutorial_name/chapter01/chapter.js in much the same way as you did for contents.js. In fact, you can follow the directions above for adding a molecular view (with one important difference, see the next paragraph), then setting its orientation and zoom, and describing it, for each molecular view in your first chapter.

initial-view.spt vs. view01.spt. In chapters (as distinct from the contents), the first view on each page is scripted in the file jtat/tutorial_name/chapter_name/view01.spt. (Actually, you can name the script file anything you want, as long as you specify the name correctly in setupButton(...) in chapter.js.) When you first enter the chapter, you may wish to have additional special effects, such as having the message Click and drag on the structure to rotate it fade in and then out, and to have the molecule roll while zooming into view (as in Star Wars). These "special effects" are needed only once, when you enter the Chapter. Generally, the user doesn't want to see them later should s/he revisit View 1. Therefore, when the chapter is first loaded, the view is generated with initial-view.spt. Later, if the View 1 button is clicked, only the view01.spt is applied. So initial-view.spt calls view01.spt (with the command script view01.spt), and adds any one-time special effects.

Replay/Reset Initial View is an optional button, present by default, that re-executes initial-view.spt, including any special effects. Often, you may decide to specify the initial orientation and zoom in initial-view.spt, but specify none in view01.spt. This means that revisiting View 1 does not change the orientation and zoom the user may have set in the previous view, allowing for better comparisons. Should the user wish to reset the view to the initial orientation and zoom, this is accomplished by clicking on the button Replay/Reset Initial View.

If the above distinctions between the initial view and View 1 are not clear, try this in the JTAT Demonstration Tutorial. Enter the chapter 1. Molecular Views, Descriptions, and Details. Note the message that fades in and out at the top of Jmol, and the rolling zoom of the molecule. Now click View 2. Rotate and zoom the molecule with the mouse and zoom slider. Click View 1 and notice that (i) the orientation and zoom do not change, and (ii) the message does not fade in/out at the top of Jmol. Now click the button Replay/Reset Initial View and note the differences.

More Molecular View Buttons. You may have as many molecular views in each chapter as needed. Simply copy the Molecular View Button block for each beyond the two provided. The buttons will appear in the order in which they occur in chapter.js. Therefore, if you want to re-arrange the order of existing buttons, simply re-arrange the order of these blocks in chapter.js.

view01.spt, view02.spt, etc. The default names for the script files for the views in a given chapter are view01.spt, view02.spt, etc. However, you may name these scripts in any way you wish, as long as you provide the correct script names in initial-view.spt and (for View 1), and in setupButton(...) (for each View button). Should you later insert a new view between, for example, Views 1 and 2, you could name its script view01a.spt or view015.spt (bearing in mind that the script for View 15 would be view15.spt).

Zoom and Cut/Slab Sliders? Please review the chapter Slider for Zoom, Cut (Slab) in the JTAT Demonstration Tutorial. Each chapter.js files contains these variables and default values:

You may have no zoom slider by setting showZoomSlider to false, but this is not recommended.

When a Cut (Slab) slider is present (set showSlabSlider to true), checking the word Cut (or Slab) cuts the molecule in half (at 50%), hiding the portion in front of the cut. Moving the slider moves the cut plane from 0% (behind the molecule) to 100% (in front of the molecule). Thus, by having a Cut Slider in a chapter, you need not cut a molecular view(s) in order for the user to see the cross section. You may simply instruct the user to check Cut (or Slab) and use the slider. Such instructions are probably best given in the description of the view. (When Cut is unchecked by checking Zoom, the front portion of the molecule is automatically restored.)

Strictly speaking, Slab means that both the front and rear portions of the molecule have been "cut away" and hidden, leaving a slab. The term Slab is often mis-used when only one cut is made, and only the portion in front of the cut is hidden. A better term for this is Cut, which is the default label for the slider. If you prefer the label Slab for this slider, change the variable slabSliderLabel from Cut to Slab.

Create Additional Chapters. To add another chapter, copy the folder jtat/template/chapter01 (with all the files it contains) into jtat/tutorial_name. Rename the new folder, e.g. chapter02. The files in chapter02 should NOT be renamed. Proceed to add molecular views, descriptions, and details as you did for chapter01.

Finishing up Chapters: Next, Previous, Contents buttons. Each chapter.js file contains navigation variables that specify the targets of the Next, Previous, and Contents buttons. Make sure these are correct as part of finishing up your tutorial chapters.

Next, provide the following specifics for the window title, and the footer material that can be viewed at the bottom of the Contents as well as every chapter.

• Title for the browser window, in jtat/tutorial_name/js4all/window_title.js. This will be displayed at the very top of the browser window, when it is displaying any part of your tutorial. In contrast, the title of your tutorial typically appears at the top of its Contents page, below the window title. The window title also labels the taskbar button in Windows, and pops up when you touch the minimized window on Macs. The window title can be the same as the title for your tutorial, but perhaps a shortened version.


• Molecules for further exploration under How To ...: Please provide the PDB codes for the molecules used in your tutorial, and a brief description of each molecule. These go in jtat/tutorial_name/js4all/molecules.js.


• Author's name, website, email and the year for copyright, feedback and download requests, in jtat/tutorial_name/js4all/license.js.


• Optional: If appropriate, you can show additional credits or acknowledgements for your tutorial, in the (initially blank) variable tutorialCredits, in jtat/tutorial_name/js4all/license.js.


• Optional: If you do not wish to use the built-in Creative Commons Attribution - Noncommercial - Share Alike 3.0 License, you may specify your own (alternative) license in the (initially blank) variable alternativeLicenseAndCredits, in jtat/tutorial_name/js4all/license.js

If you set noSpinning to true (see Convenience Settings While Authoring), be sure to restore it to false before deploying your tutorial!

Provide an Introduction? Optionally, you may provide an introduction to your tutorial that users will see before they enter the Contents page that shows Jmol. A skeleton for such an introduction is provided in the file jtat/template/intro.htm. If you use this file, you may rename it to index.htm (a conventional starting place), or else you will need to change the link in jtat/index.htm to go to intro.htm.

Project your Tutorial from your private copy. When your tutorial is completed, you can project it from a computer (or stick/thumb memory) to illustrate lectures, without putting it on the web. We hope you will also put your tutorial on the web so your students as well as other educators and students can benefit from it.

Note: All of your tutorial is in the jtat folder. To copy it to another device, simply copy jtat and all the files and folders that it contains. To view the copy, please review Viewing Your Tutorial.

Put Your Tutorial Online! Putting your tutorial on the web requires that you have an account on a web server (http server). If you are at an educational institution or corporation, typically the information technology department of your institution will provide the server account and help in using it.

If you would like an independent, free web server, we recommend that you apply to bioinformatics.org for what they call a project. First, you'll need to create a login account for yourself: click on the "Log In" link near the upper left, and on the login page is a link for New account. After you have logged in, at the upper left of the main page, you'll see Logged in: yourname. Below that is a link Register new group/project. Once approved, your project includes a place where you can put your jtat folder and all its tutorials. If you would like help setting up your tutorial on bioinformatics.org, feel free to contact me (emartz@microbio.umass.edu).

If you have more than one tutorial in one jtat folder, you can provide a list of them, with links to each, in the file jtat/index.htm. By default, this file redirects to the main page for JTAT. To use it for your tutorials, copy the file jtat/index2tutorials.htm to jtat/index.htm. Then edit the new index.htm to make the links to your tutorials.

What is a "script"? The term "script" is short for "command script", which is a series of commands to Jmol that specify how to render a molecular view. Typically these commands are stored in a plain text "script" file, with a filename ending ".spt".

Optional: If you want to examine some script files now, look at the files ending in ".spt" in the jtat/jtatdemo/ch_* directories. Note, however, that these were all created by direct scripting rather than being state scripts generated by Jmol.

There are several ways to generate these molecular view scripts.

• Saving state scripts. Proteopedia.Org's Scene Authoring Tool is the easiest way to create scripts for JTAT. In brief, you get the molecular view you want by any combination of these three methods:
  1. Using the dialogs in Proteopedia's Scene Authoring Tool (the easiest method, yet quite powerful).
  2. Optionally, by using Jmol's menu within Proteopedia (slightly more technical).
  3. Entering commands directly into Jmol's Console (varies from fairly simple to very technical, depending on what you are doing).
  4. Instead of using Proteopedia, you can use FirstGlance in Jmol to generate a view and then a state script. Instructions are below.
  Regardless of which method you use to get the desired view, Jmol then creates a command script for you (called a state script) that precisely describes the current view. You simply copy and paste this state script into a .spt file in JTAT. Detailed instructions are below.


• Editing state-scripted views. To change a state-scripted view, you first run the state script in Jmol (e.g. via Jmol's Console, in Proteopedia). You then change the view by any of the means mentioned above, and generate a new state script, which replaces the one in the relevant .spt file.


• Direct script authoring and editing. Command scripts can be typed directly into .spt files. This requires technical knowledge of Jmol's command scripting language. The difficulty varies with what you want to do. One advantage is that the full range of Jmol's capabilities can be used, provided you are willing to figure out how. Another advantage is that the scripts will be relatively short and easy to modify by direct editing. State scripts, in contrast, are long, not very human-readable, and not easy to improve by direct editing. This is not much of a disadvantage given the ease with with they can be changed (see previous paragraph). Detailed instructions for direct scripting are provided.

Scripting in Proteopedia is recommended because it is easiest and can produce a wide range of molecular views that will meet most needs. Some advanced molecular views (such as translucency, cavity surfaces, or crystal symmetry operations) will not be available in the dialogs of Proteopedia's Scene Authoring Tool -- in these cases you could enter script commands into Jmol's Console within Proteopedia.

Before using Proteopedia to make molecular view scripts for JTAT, you should first have tried creating a tutorial directly in a Proteopedia wiki page. Molecular scenes in such a page can easily be moved later into script files for JTAT following the instructions below. You don't need to use the procedure below unless Proteopedia seems too limiting, and you want to try using JTAT instead.

Terminology: The terms "view" and "scene" mean the same thing here. The JTAT documentation uses "molecular view" while Proteopedia uses "molecular scene".

A. Making JTAT scripts in Proteopedia:

1. You will need a page in Proteopedia in which to author molecular scenes, unless you have already authored the scenes that you want to put into JTAT. For this purpose, you can create a protected page named Scenes for [topic of your tutorial] in JTAT. (see Help:Protected Pages).


2. Obtain the desired molecular scene in Proteopedia. It does not matter which of the following methods you use to obtain the scene. Jmol will generate the appropriate state script regardless.


• Use Proteopedia's Scene Authoring Tool. Proteopedia contains ample help for how to do this. This is the recommended method because it is powerful, and by far the easiest.


• Use Jmol's menu. To open the menu, click on Jmol at the lower right corner below the molecule. Changing the scene with the menu can be somewhat technical. Jmol's menu has no help, so you will have to experiment. Most things on the menu can be done more easily in the dialogs of Proteopedia's Scene Authoring Tool. Unless you just like the menu better for a particular purpose, a good reason to use Jmol's menu would be if you find something there that can't be done in the Scene Authoring Tool.


• Open Jmol's Console from Jmol's menu (see previous paragraph). Then enter commands directly into the input (bottom) box of the Console. For more information on Jmol's command language, see Direct Scripting.


3. Display the state script in the output (top) box of Jmol's Console. (See above for how to open the Console.) With the Console open, click Clear Output, then State.


4. Copy and paste the state script.
• Windows: Click on the state script in Jmol's Console, then select all (Ctrl-A), then copy to the clipboard (Ctrl-C). Paste the state script from the clipboard into your text editor (Ctrl-V).


• Mac OS X: Click on the state script in Jmol's Console, then select all (Cmd-A). With the entire state script selected, drag it and drop it into your text editor. (Copying to the clipboard does not work due to a bug in java.)


5. Disable the load command! The state script includes a command that begins with "load", designed to load the molecular model (typically a PDB file). This command must be disabled. (JTAT loads the molecular model separately before running the state script.) Disable this one command line in the state script by putting a pound sign (#) before the word "load", making it "#load". This converts it from an executable command into a comment. For example, here are 5 lines from a state script that include the "load" command as the middle line. It has been disabled:

     set percentVdwAtom 20;
     set smartAromatic true;
     #load /*file*/"http://proteopedia.org/cgi-bin/getpdbz?1eve";
   
   end function;
   
   function _setVariableState();

6. Save the state script into a script file in the folder containing the chapter where the scene/view will be displayed. For example, if that is Chapter 1, save the script file into jtat/tutorial_name/chapter01. The filename must end with .spt.

B. Editing JTAT scripts in Proteopedia:

Suppose that you already have a molecular view in JTAT that you scripted in Proteopedia, but you want to make changes. If it will be easier to modify the existing scene than to re-create the desired scene from the beginning, here is how.

1. If the existing scene is still present in the page in Proteopedia where you created it, simply edit that Proteopedia page, open the Scene Authoring Tool, and load the existing scene.


If the existing scene is no longer available in Proteopedia:
1. Edit the appropriate page in Proteopedia.
2. Open the Scene Authoring Tool, and load the relevant molecule.
3. Open the JTAT .spt file for the existing scene in your text editor.
4. Transfer the script from the .spt file into Jmol's Console.
• Click on the Jmol frank to open Jmol's menu, then click Console.
• Windows: Copy the script commands from the .spt file to the clipboard, and then paste them into the bottom box of Jmol's Console.
• Mac OS X: Select the commands in the script file, and then drag the selected block of commands and drop it into the bottom box of Jmol's Console.
5. Execute the script. Now you should see the existing scene.


2. Use any of the methods listed above to change the scene. Then, continuing as above: display, copy and save the state script into the .spt file in JTAT.

You can also put molecular views obtained in FirstGlance in Jmol into JTAT script files. To do this, it is crucial that you start FirstGlance from within Proteopedia, using the link to FirstGlance beneath each Jmol display (on pages titled with a PDB identification code). These links within Proteopedia start the beta version of FirstGlance, which should be using a version of Jmol that is matched to the Jmol version used in Proteopedia and JTAT. Mismatches between the version of Jmol used to generate the state script, and the version asked to run it, may cause the molecular view to fail to appear, or to be incorrect. (For more on this, see Troubleshooting Scripts.)

Certain views that are obtained very easily in FirstGlance are very difficult to obtain in Proteopedia. These include any view generated with the Contacts.. dialog, as well as (under More Views..) the display of all salt bridges or all cation-pi orbital interactions.

As in Proteopedia, scenes obtained in FirstGlance can be modified by direct command entry into Jmol's Console before you transfer the state script. It would also be possible to transfer a FirstGlance state script into Proteopedia (by transfering it into the console and executing it), and then modify it with Proteopedia's Scene Authoring Tool. Then you could transfer the final scene from Proteopedia to a .spt file for JTAT.

Once you have obtained the desired molecular view in FirstGlance, display and transfer the state script into a .spt file, following the instructions above.

Direct scripting will be unnecessary for most JTAT tutorials. Therefore, most authors of JTAT tutorials will not need to learn direct scripting.

Learning how to make molecular view scripts is the most technical option for authoring tutorials with JTAT. If you have some knowledge of the command languages for RasMol or Chime, Jmol scripting will be very similar for basic operations. However, Jmol has many capabilities not present in RasMol or Chime.

Select atoms, then display and color them. In Jmol, as in Chime and RasMol, you select a subset of the atoms first, and then apply a display style and/or color or color scheme to them (or hide them). Next, you can select a different subset of atoms, and so forth, until the desired molecular view is complete.

Jmol's menu can be used for selection, display and coloring in either the application or the applet. Jmol's menu is cumbersome for more than a few operations, and lacks help, but may be used if you wish.

Script Command Reference Manual. The commands understood by Jmol are listed and explained in a master Jmol Command Reference Manual. Here you will find detailed descriptions of each command, often together with examples demonstrating their uses. Because Jmol is under rapid development, the documentation sometimes lags behind current Jmol behavior. If, after consulting the documentation, questions remain, don't hesitate to ask for help at the Jmol-users email list.

Jmol's command language is a superset of the language used by the MDL Chime browser plugin, which was popular from its inception in 1996 until Jmol became macromolecule-capable, around 2004 (see the Chime-based tutorials, being phased out, at molviz.org, and many more at molvisindex.org). In turn, Chime's command language is a superset of the language invented by Roger A. Sayle for RasMol, a very popular stand-alone molecular visualization application that became available in 1993. Thus, the Jmol language is easier to learn for those already familiar with the Chime or RasMol languages.

Jmol is preferable to RasMol because RasMol does not work in a web browser, and has no support for tutorials. Chime has not been developed for a decade, is not open source, and is difficult to get to work by today's standards (see About Chime).

Help: the Jmol-users email list. This is a very active email discussion of Jmol use. Not infrequently over a dozen messages are broadcast in a single day. This is the place to ask for help, to report bugs, and to make suggestions for enhancements. Suggestions for enhancements may also be entered as Feature Requests. At http://jmol.org, click on the Projects link near the upper right. There you will see the links for Feature Requests, and for the jmol-users mailing list. It is best to subscribe before you ask for help, so you can see the replies. If you don't want to keep receiving all the broadcasts, you can always unsubscribe, possibly resubscribing again later if you have more questions.

Sooner or later, you will save a Jmol command script file (such as view01.spt), but when you click the corresponding View # button, you do not get the desired view (or you get no view at all). Troubleshooting Jmol scripts is straightforward. Here is how.

Make sure you don't have a javascript error. Before working on the .spt file, make sure there are no javascript errors by checking the javascript error console, as described under troubleshooting in Editing Javascript Files: Finding and Fixing Problems.

Confirm which .spt file is the culprit: Show History. It is frustrating to spend time inadvertantly trying to debug the wrong .spt file, so first, make sure you know which one has the problem.

Reload the chapter (click on the browser's reload/refresh button) so only the initial view has been displayed. Next, click the button for the view in question. (Don't click other views first, as they will add confusion.) Open Jmol's menu:

In Jmol's menu, click Show, History. The Jmol Console window will open, and the commands that have been sent to Jmol will be listed.

The command history shows all commands sent to Jmol since the applet was first loaded in the chapter. The initial view script block will be between these comments:

Within this block will typically be the command "script initial-view.spt", since that is the default script file used for the first view in a chapter. Before and after this line will be other commands that JTAT automatically adds to the .spt file itself.

Following the initial-view script will be the script for the view button you pressed. For example, if you pressed "View 5", it will be between these comments:

Between these comments will be the script command that calls the script for the view in question. Typically, for View 5, this would be script view05.spt. This is the script file name you are looking for to confirm which script file needs debugging.

Note that the commands within a script file (*.spt) are not shown in the history. For example, the file "initial-view.spt" typically includes the command "script view01.spt", but this will not be listed in the history. There are two ways to see all of the commands received by Jmol. One is to open the .spt file(s) in a text editor. The other is to use "set debugscript on" (see next section below).

Make sure your Jmol versions are matched. If the malfunctioning .spt file in question is a state script saved from Proteopedia or FirstGlance in Jmol, check the versions of the Jmol applet in the application that generated the state script, and in your copy of JTAT. Open Jmol's menu in each application, and touch About Jmol. The submenu that opens begins with Jmol's version. The state script should work if the versions are the same, or nearly the same. If they are not, you can change the version of the Jmol applet used by your local (downloaded) copy of JTAT to be closer to the one in use by Proteopedia (or FirstGlance in Jmol).

Before you change the Jmol version in JTAT, we recommend that you try finding the first invalid command, as explained below. If the Jmol versions are different, bear in mind that the command may be invalid because of the difference in Jmol versions.

If you decide to change the Jmol version in JTAT, here is how:

Find the Jmol command that isn't working. Jmol command scripts typically fail because a single command is syntactically invalid (cannot be understood by Jmol). When one command is invalid, Jmol typically stops executing the entire remainder of the commands in the script, often displaying no molecule at all.

Invalid commands are reported in the Jmol Console (available from the Jmol Menu) as "script ERROR:" followed by details.

Invalid commands are also reported in the Java Console. On rare occasions, you may find the error there more easily than in the Jmol Console. To open the Java Console:

If the molecule shows but the view is not what you expected, it is very helpful to be able to see the actual commands Jmol executed, in order. To do this, open Jmol's Console from the Jmol Menu. In the Console's lower box (command input box), type "set debugscript on" and press Enter. Make sure that you typed it correctly by noting whether any error is reported in the top box (output box). Also you can find out whether debugscript is on or off (true or false) by entering the command "show debugscript".

With debugscript on, click the "Clear Output" button in the Jmol Console. Now, click a view button in your tutorial. The output box of Jmol's Console will list every command executed, in order, including commands within script files (*.spt).

If your tutorial has multiple-molecule views, you first need to display a view with the number of molecules that are in the view you wish to debug. Then open the console for one of the Jmols (or for as many as you wish -- multiple Jmol consoles can be open at once), set debugscript on, and proceed as above. If the number of Jmols (molecules) changes when you click the problematic view button, then new Jmol(s) will be loaded, and these will not have debugscript turned on.

Opening Jmol's Console Automatically. The above scheme shows all commands and all errors. Often, however, you will be primarily interested in debugging commands in a particular script file. This can also be done by inserting two commands into the script file, at the top, one to open the console, and one to turn on debugging:

This method does not report commands that are automatically inserted by JTAT before and after your script file. However, if you now click "Clear Output" and press the problematic view button again, the console is already open and debugging is already on, so on this second pass, you will see all commands.

After you have debugged the script file, and the desired molecular view is being achieved, you can either delete the above two commands, or comment them out by prefixing them with the pound sign (#), as follows:

Help! If you have a frustrating problem that you haven't managed to debug, please contact the jmol-users email list (see last paragraph at Direct Scripting) or me (emartz@microbio.umass.edu).

The DRuMS Standard Color Schemes. Careful selection of colors can help your structural views to communicate effectively, and enhance their attractiveness. Unless there are compelling reasons to do otherwise, we recommend that you use the DRuMS Standard Color Schemes illustrated in the JTAT Demonstration Tutorial and below. These build upon colors used for elements in physical models, and upon the color schemes for secondary structure in RasMol, Chime, and Jmol, and extend them to nucleotides and chemical composition. The colors are designed to be distinguishable when any or all schemes are combined, to the extent feasible. In addition to JTAT, DRuMS is used in Protein Explorer, FirstGlance in Jmol, and Biochemistry in 3D, the latter being tutorials designed to complement Lehninger Principles of Biochemistry, and elsewhere.

Jmol vs. DRuMS. The original DRuMS Color Schemes were proposed in 2000. Later, when Jmol was enhanced for macromolecules, its default colors for some elements (those less common in macromolecules) were changed, after careful consideration. Hence, while the colors for C, H, O, N, P, and S are similar in Jmol and DRuMS, Jmol's colors for other elements are different. JTAT's built in support for color schemes follows Jmol's default colors.

JTAT vs. DRuMS. JTAT (first released in 2008) extends the 2000-vintage DRuMS color schemes in a few places with additional or modified colors. These extensions follow, for the most part, similar extensions that were made in Protein Explorer (first available in 1998) and FirstGlance in Jmol (first available in 2005).

JTAT's Support for Color Schemes. Proteopedia's Scene Authoring Tool and JTAT both support DRuMS color schemes. JTAT provides script files that apply DRuMS color schemes to selected atoms, style sheets for applying DRuMS colors to HTML text, a copy-and-paste Text Coloring Quick Reference, and javascript functions to generate color key text for the standard color schemes. Below are explanations of how to use all of these.

The word DRuMS represents the people who created it: Tim Driscoll, Frieda Reichsman, Eric Martz, and Roger Sayle. Sayle is the creator of RasMol and its color schemes.

JTAT makes it easy to apply standard (DRuMS) color schemes to your molecules by several methods.

Proteopedia. If you are using Proteopedia to generate your view scripts, it provides several DRuMS color schemes at the touch of a button. In Proteopedia's Scene Authoring Tool, in the colors tab, the following are DRuMS color schemes:

• Element (CPK)
• Secondary Structure
• Composition
• Hydrophobic/Polar (called "Polarity2" in Protein Explorer)
• Charge (2, 4, or 5 colors)

With the exceptions of amino and amino 2, the other color schemes in Proteopedia's Scene Authoring Tool are also quite commonly used, although not formally part of DRuMS.

Direct Scripting. If you are writing your own scripts by hand, you may use Jmol's built-in DRuMS color schemes for element or secondary structure, or ready-made DRuMS coloring scripts provided with JTAT. Assuming the script file calling these coloring scripts is in a contents or chapter folder, these can be called as follows in .spt files:

There are four ways to make color keys in the text of your molecular view descriptions.

1. For standard color schemes, there are JTAT color key functions, for example composition_key(). More..
2. For standard DRuMS colors, you can color a single word or phrase with a CSS style class. For example, if you want to spell out the word Carbon instead of showing only the "C" displayed by element_key("c"), you can use <span class="c">Carbon</span>. More..
3. For any arbitrary single color, you can use JTAT's function ckey("[hex RGB value]", "text"). This puts the text in the standard color key font. More..
4. For any arbitrary single color, when you want the color key to be in the same font as the surrounding non-colored text, rather than the standard color key font, you can use ordinary HTML tags, for example <font color="#[hex RGB value]">text</font>. More..

Below are explained how to use each of these, and all the standard color keys are shown.

A. JTAT's functions for standard color keys are javascript functions, each of which returns a colored text key. For example, the function composition_key() returns the HTML to display this:

First, we'll explain how to use these functions. Then we'll list all the color key functions provided by JTAT.

How to use JTAT's color key functions. All the *_key() functions have one optional parameter, which is the final punctuation. Typically, this is ", " (comma space) when followed by another color key, "." (period) when the end of a sentence, or ":" (colon) when preceding a statement. For example, composition_key(".") returns this:

When authoring a JTAT tutorial, text, such as a molecular view description, is written into a javascript file (either chapter.js or contents.js). It is written as a character string variable (see javascript above). In order to combine a javascript color key function with such a string, it must be added (concatenated) onto the string. So, the string must be ended with a closing quote, followed by a +, followed by the function. If more quoted text is to follow the color key, again, it must be added with a + after the function. For example:

  // MOLECULAR VIEW DESCRIPTION
  buttons[buttonNumber][iButtonText] =
"The composition of this molecule is: "
+ composition_key(".") +
" (This is a DRuMS standard color scheme.)";

which will display in the tutorial like this:

Multiple color key functions can be added together. For example, if the molecule has only protein, ligand, and solvent, the color key can be generated as follows:

  // MOLECULAR VIEW DESCRIPTION
  buttons[buttonNumber][iButtonText] =
"This molecule consists of "
+ protein_key(", ") + dna_key(", ") + solvent_key(".");

which will display like this:

The default font for color keys is intentionally large and bold in order to be easily visible in Windows browsers, where the weight of the normal sans serif font is low (compared to its weight in Mac browsers, where it is more readable). If you want to experiment with changing the color key font, uncomment and modify the variables colorKeyPrefix and colorKeySuffix in jtat/tutorial_name/js4all/tutorial.js. (The primary definitions are in jtat/_jsutil/keys.js.)

Complete list of JTAT's color key functions for standard color schemes.

B. Color key text with HTML style class spans. Every standard JTAT/DRuMS color has a syle sheet class name. For example, in the Composition color scheme, solvent is the name of a color. The JTAT color key function solvent_key() returns:

However, if the only solvent in the molecule at hand is water, you might prefer to apply the solvent color to the word Water. This can be accomplished using

which displays like this:

Note that when combining two style classes, they must be separated by a space, without a comma. Note also that combining the color class solvent with the font class keyfont (as above) produces the standard color key font. If you want the font to be the same size and style as the surrounding text, omit keyfont, like this:

which displays as follows:

(Color key text is always bold weight. This is included in the color key style classes.)

The complete list of color key style classes is in the

Colored Text HTML Quick Reference    

where it is easy to copy and paste the complete span tag for each color you need.

C. Color key text in non-standard colors and the standard color key font: the ckey() function. When you want to color text with a non-standard color, and you want the text to be in the standard color key font, use the ckey() function. It takes three parameters:

1. RGB (red-green-blue) hexadecimal color value. To find these values, please see the lists at the bottom of the Jmol Colors page. Give just the six hexadecimal numbers, without the #.
2. The text to be colored.
3. Optionally, terminal punctuation that will not be colored.

For an example, in the JTAT Demonstration Tutorial, in the chapter on Animations and Movies, View 1 uses non-standard colors for DNA and sulfur. This was done in order to distinguish the two strands of DNA clearly, and to distinguish the disulfide bond (normally colored the same as sulfur) from beta strands. The color key is:

The above was produced with this javascript:

ckey("ff9090", "DNA", "/") + ckey("a0a0ff", "DNA", ", ") +
ss_key(", ") +
ckey("ff8000", "Disulfide bond", ".")

D. Color key text in non-standard colors and the default font: the HTML font tag. When you want to color text with a non-standard color, and you want the text to be in same font as the surrounding non-colored text, specify the color with an HTML font tag. The color can be either an RGB code or a color name. These can be gotten from the Jmol Colors page. Enclosing the colored text in boldface tags <b>...</b> makes the colors easier to see.

displays as follows:

Font color tags are used, for example, in the JTAT Demonstration Tutorial, in the chapter on Spin Control.

Disabling Automatic Spinning. When you are constantly reloading a page (and not testing the automatic spinning controls), you may not want to have the molecule start spinning on every test. Spinning is a siginficant load on your computer, and may, for example, cause the speed of the CPU fan, or the CPU temperature, to increase. Set noSpinning to true in jtat/_jsutil/config2.js and you won't be bothered. But please remember to set it back to false before putting your tutorial on the web!

Below are described methods to change some of the default behaviors of JTAT. These are all optional, and only advanced users need be concerned with this section.

Default Text Font and Weight The default font face for text in tutorials is Verdana (sans-serif), with a default size of 1em. These can be changed for a particular tutorial in jtat/tutorial_name/js4all/tutorial.js in the section Control Panel Text Style. They can be changed for all tutorials in the setTextFont*() functions in jtat/_jsutil/config.js

The default font weight for Apple Mac OS X and Linux is "normal". For Windows, bold was chosen as the default for all control panel text because the normal fonts in Windows Firefox and Internet Explorer are rather thin and hard to see, especially for projection. This means that explicit bold weight text in Windows is no different than the rest of the text. The default weight can be changed as in the previous paragraph.

Style of Chapter Links in Contents are set with the style class="contents", which is defined in jtat/_cssutil/jtat.css. This style could be changed for one tutorial by re-defining the .contents classes in jtat/tutorial_name/css4all/tutorial.css, or for all tutorials by editing the definitions in jtat/_cssutil/jtat.css.

Color Key Text Style is specified by colorKeyPrefix and colorKeySuffix in jtat/_jsutil/keys.js. If you want to change it for all tutorials, change it there. If you want to change it for one tutorial, change these variables in jtat/tutorial_name/js4all/tutorial.js.

Replay/Reset Initial View Buttons are, by default, present at both the bottom and top of the control panel for each chapter. If there is no difference between initial-view.spt and view01.spt, you do not need any Replay/Reset buttons: set provideResetButton to false in chapter.js. If you want a Replay/Reset button at the bottom, but not at the top, set showResetInitialViewButtonAtTop to false in chapter.js. If you want this for all chapters in one tutorial, set it to false in jtat/tutorial_name/js4all/tutorial.js.

Optional Credits or Acknowledgements, to be displayed at the bottom of every chapter in a tutorial, can be specified in tutorialCredits in jtat/tutorial_name/js4all/license.js. The required credits, copyright year, etc. are also specified there.

A custom license for your tutorial, to be displayed at the bottom of every chapter, can be specified in alternativeLicenseAndCredits in jtat/tutorial_name/js4all/license.js. If this variable is not blank, it will replace the default Creative Commons Attribution - Noncommercial - Share Alike 3.0 License displayed in all JTAT tutorials. That is defined in jtat/_jsutil/licenses.js. Please don't change it, but a mechanism is provided there to add another standard license, and specify it. See also the previous paragraph here.

The core of a JTAT tutorial is the series of molecular view buttons, each of which displays a different molecular view. For the most part, this mechanism is satisfactory. In some cases, however, it is useful to make minor changes to a molecular view without having an entire new view button. One way to make such small changes is with checkboxes. An example is the first view in the chapter Color Schemes: DRuMS in the JTAT Demonstration Tutorial. In this instance, each checkbox shows or hides a component of the molecule.

Jmol.js, which comes with Jmol, includes functions to create checkboxes, pull-down menus, radio buttons, and links (which we'll call collectively controls) that send command scripts to Jmol. These functions cannot be used to write these form elements directly into a JTAT chapter.js file for for technical reasons. Instead, after a chapter page has loaded and Jmol has been initialized, the HTML for the controls is created and inserted into a pre-existing division. If you wish to try using any of these controls, you should examine the implementation in jtat/jtatdemo/ch_drums while following these two steps.

1. In the file jtat/tutorial_name/chapter_name/chapter.js, in the button description text or other text element, insert an empty division with the id "jcontrol1" where you want checkboxes to be placed. Follow the example in jtat/jtatdemo/ch_drums/chapter.js. (If you later want another set of controls in the same page, name its division jcontrol2, and so forth.)


2. In the file jtat/tutorial_name/chapter_name/jcontrol.js, insert javascript in the function writeJmolControls() that will generate the HTML for the checkboxes you need, including the desired Jmol scripts to be executed when checked or unchecked, and insert the HTML into the appropriate division(s). Follow the example already provided in that file. Look in jtat/jtatdemo/ch_drums/jcontrol.js for working examples.

The same strategy should also work for pull-down menus and radio buttons, but I have not tested it. Also I have not attempted to design checkboxes for multiple-Jmol views, but it should be straightforward. Don't hesitate to ask for help: emartz@microbio.umass.edu.

Animations vs. Movies. We'll use "animation" to mean an animation that plays in Jmol, and "movie" to mean a true movie -- a series of still photos played in sequence. If you haven't already done so, please review the chapter on Animations and Movies in the JTAT Demonstration Tutorial. The key difference is that an animation in Jmol can be viewed from any perspective (by rotating it with the mouse), while animating. A movie has only one perspective (or a limited, pre-determined set). Also, the color scheme and rendering can be changed easily in Jmol to show different aspects of the animation, while a separate movie is typically required for each such change. Finally, animations in Jmol typically require transfer of less than one tenth of the amount of data through the Internet than does a movie.

Therefore, animations in Jmol are a powerful and efficient way to show molecular conformational changes at atomic level resolution. How to make and use them in JTAT is discussed in the next section. Generating a molecular movie showing a molecular conformational change usually involves first making a multiple-model interpolated or morphed atomic coordinate (PDB) file. Once you have such a file, for display in a JTAT tutorial, there are many advantages to animating it in Jmol, rather than using it to make a true movie.

When Are True Movies Best? In a JTAT tutorial, there are two good reasons for including a true movie. The first is when the movie is already available (along with permission to use it!), thereby saving you the time needed to create your own animation. The second is when the movie shows something that would be difficult or impossible to represent in Jmol, such as cartoons of higher level structures. Examples of atomic-level movies that would be difficult to animate in Jmol (due to the kinds of atomic models that would be required) are some showing DNA recombinations moving through Holliday junctions.

On the other hand, in a Powerpoint presentation, movies are great because incorporating Jmol is either impossible (Macs) or technically tricky (Windows). (To create movies for Powerpoint, see Top5.MolviZ.Org.)

Typically, an animation of a conformational change starts with two empirical PDB files representing two conformations. Unless the change is very small (slight shifts of a few sidechains), intermediate models will need to be interpolated in order to see and understand the structural changes. This is called molecular morphing. The main purpose of such morphing is not to predict the actual trajectory of the change, but to allow one to follow it with the eye. (For examples, beyond the JTAT Demo Tutorial, here are morphs and movies that I made using RasMol and Chime in the pre-Jmol era.)

The resulting multiple-model PDB file can then be animated in Jmol with a few simple commands, such as:

anim mode palindrome;
anim on;
anim fps 8;

These commands can be seen in action in the chapter on Animations and Movies in the JTAT Demonstration Tutorial, for example, in jtat/jtatdemo/ch_anim/view01.spt.

Protein Explorer has an NMR Models and Animation control panel which is quite powerful for viewing animations of multiple-model PDB files. But it works only on Windows in Firefox, and requires that you install the free plugin MDL Chime. For more details, go to ProteinExplorer.Org.

Creating a Morph PDB File. The easiest way to morph between two empirical PDB files is by submitting them to the Yale Morph Server. This server first does a linear interpolation (see below), and then a little energy minimization on each step, producing a "chemically possible" trajectory. Yale will generally produce a satisfactory result unless you want to show ligand(s) in the animation. It can handle multiple chains including both protein and nucleic acid chains, and it can handle the situation when the empirical models have somewhat different sequences. Don't hesitate to ask the Yale team for help if at first you don't succeed -- they have been quite helpful to me.

Ligands in a Morph. Although the Yale Morph Server will strip any ligand out of submitted PDB files, you can put a ligand back into the morph it produces -- provided you only want the ligand in the starting or ending model. This is what is typically needed when the ligand induces the conformational change. The ligand ATOM lines of the PDB file can simply be copied into the appropriate (first or last) model in the morph PDB file. However, it may need to be realigned first. This can be done with the free program DeepView. If you need help, please contact me directly (emartz AT microbio DOT umass DOT edu -- I enjoy making morphs) or contact the molvis-list.

Linear Interpolation Morphing. If the Yale Morph Server does not produce the result you seek, you can perform a simple linear interpolation using free software that I wrote. Its big limitation is that the starting PDB files (first and last frames of the animation) have to have exactly the same atoms in the same order. In a linear interpolation, each atom moves in a straight line between its initial and final positions. This causes bond lengths and angles to violate normal values, and may even cause atoms to pass through each other. The result is a "chemically impossible" trajectory. However, obvious violations of chemistry serve to remind the viewer of the usual purpose of a morph (see above). Again, feel free to contact me for help or a collaboration on morph construction (emartz AT microbio DOT umass DOT edu).

Movie Formats vs. Browser Compatibility If you are going to use a movie in JTAT, you should be aware of the following issues concerning the data formats of movie files.

• All multi-gif (.gif) and some .mpeg formats are best because they work in all popular browsers without installing any special movie players.


• Quicktime movies (.mov) work in the Safari and Firefox browsers in Mac OS X because the requisite Quicktime browser plugin comes bundled with Macs. However, in Windows, users will have to download and install free Quicktime.


• Windows Media Video (.wmv) movies work in Internet Explorer and Firefox on Windows, because the requisite player is bundled with Windows. However, Mac OS X users will have to download and install a free plugin to enable them to play this movie format. One solution is available from Flip4Mac.

Making a Molecular Movie. The Polyview-3D server is the easiest place to create publication-quality movies of macromolecules. It produces multi-gif (.gif) movies that work in all popular browsers without installing any special plugins. If you want a really simple movie, such as a molecule rotating about its vertical axis, or rocking back and forth, all you need is a PDB code or PDB file.

If you want to animate a conformational change, you'll need a multiple-model "morph" PDB file. For information on creating these, please see Animations.

If Polyview-3D does not lend itself to the rendering you want in your movie, you can make an mpeg with the Jmol application. This will involve direct scripting. The Jmol application can write jpeg files, so you can write an animating script loop that writes a jpeg file for each step in the animation. You can then assemble these .jpeg files into an mpeg movie. We are told that this can be done with the free program GIMP, but we have no experience with this. For help, please ask on the jmol-users email list.

How do you put a movie in JTAT? Small movies can be placed directly in the control panel of a JTAT Tutorial, as illustrated in the chapter on Animations and Movies in the JTAT Demonstration Tutorial. Also illustrated there is the use of a link in the control panel to open a new browser tab or window to show a large movie. If you want to use a movie in your tutorial, please take a look at the code in jtat/jtatdemo/ch_anim/chapter.js, for a small movie in the control panel (look for lacrep_anim_small.gif), or jtat/jtatdemo/ch_anim/lacrepan.htm, for a large movie in a separate window.