User:Eric Martz/How JSmol works

This is intended to be a minimally technical overview of how JSmol and Jmol work in websites, such as Protopedia, FirstGlance in Jmol, and many others.

Providing JSmolProviding JSmol

The website server provides not only the web pages, but also JSmol. The web browser simply displays JSmol, and molecular data, provided by the server. Thus, the version of JSmol is matched to the web pages. JSmol is updated frequently at Jmol.Org, but the version of JSmol on a given website remains fixed until the site administrator upgrades it.

A website has, at the very least, some hypertext markup language files (filenames ending .htm or .html). Usually there are also some image files (filenames ending .png, .jpg, .gif, etc.) for images that are displayed in the web pages. And usually there are also some JavaScript files (filenames ending .js) and some cascading style sheet files (filenames ending .css). JavaScript (not to be confused with Java) is a programming language that is interpreted by the web browser.

In order to invoke JSmol, the files on the website server must also include the javascript code for JSmol (filenames ending .js). If the Jmol Java applet is to be invoked, the Java archive files for Jmol (filenames ending .jar) must also be included. All these are included in the download package from jmol.sourceforge.net/download.

Invoking JSmolInvoking JSmol

The HTML page invokes JSmol, specifying a position on the page and a size. Generally, there is a JavaScript Info variable (Info = {...}) that specifies whether JSmol or Jmol is to be invoked, the size in pixels, and optionally the initial molecule to be displayed, and the display style (JSmol script commands), and other options. This Info variable is then referenced in the actual invocation of JSMol.

The actual invocation generates the necessary HTML by a JavaScript call to Jmol.getApplet() or Jmol.getAppletHtml().

Examples can be seen in the files supersimple.htm, simple.htm, simple_old.htm, etc. These and other demonstration files will be found in the jsmol directory in the downloaded package from jmol.sourceforge.net/download. You can drag these files and drop them into a web browser to see the web pages they generate.

Displaying MoleculesDisplaying Molecules

JSmol is designed to display data files that contain atoms; that is, atomic resolution molecular models. The data file lists atoms, specifying the position in space of each atom (usually in Cartesian coordinates X, Y, Z), the chemical element of the atom, and for macromolecules, the amino acid or nucleotide residue name to which the atom belongs, its position within the residue (e.g. alpha carbon, beta, gamma, etc.), the polymer chain to which the residue belongs, and its sequence number.

Such molecular structure data files are called atomic coordinate files. JSmol is able to read more than 50 formats of such files. The most common are XYZ format for small organic compounds (usually <100 atoms), and PDB or mmCIF formats for macromolecules.