Jmol JavaScript Object/Installation

Installation of JSmol

The Jmol team appreciates all feedback from web page developers and makes every effort to keep the files up to date. Please file a bug report if you find a problem.

Getting the Files

JSmol (usual name for the Jmol JavaScript Object) is included as part of the Jmol package. Full releases of J(S)mol may be obtained at the Jmol Project page.

The distribution is a zipfile, Jmol-xxx.zip, that contains Jmol.jar (the Jmol application) and a jsmol.zip file which in turn contains the whole set of files potentially needed for deploying JSmol in a webpage. Note that usually you don't need the full set of files for operation, as described below.

In summary

• For pages that use the HTML5 modality of JSmol, you just need JSmol.min.js and j2s (A total of about 36 MB, but only those parts actually needed in each occasion will be downloaded to the client computer).
• js is only important if you want to experiment with the code (advanced).

In detail

jsmol.zip (which is included inside the Jmol distribution zip file) contains a jsmol_dev.htm file which is a test an demo page, and a jsmol folder which holds all these files and folders:

• Major files:
  • JSmol.min.js The only library that needs to be called explictly; it will take care of calling any of the other files as needed. (This includes a set of files minimized using the Google Closure Compiler)
    • JSmol.min.nojq.js An alternative version, to be used if you are not loading binary files and you already use jQuery on your page; this one bypasses the JSmoljQuery.js internal component.
  • JSmol.lite.js is a lightweight version of JSmol that will load very fast and offers minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at phones and systems with limited power, or as a quick first-look option that may be programmatically replaced by a full JSmol at user request.
    • JSmol.lite.nojq.js An equivalent version that does not include jQuery (useful if you are already using jQuery in your page).
  • JSmol.GLmol.min.js is a supplementary library addressed at using a WebGL modality of the Jmol Object. Note that this does not support the full functionality of Jmol and is not under active development.

• php
  • jsmol.php or jsmol2.php A server-side PHP utility that allows a number of functions that can increase the platform and browser compatibility of JSmol. By default, JSmol will try to use a copy of this file at the St.Olaf server, but you need to put a copy in your own server in order to get full cross-platform compatibility in the following areas:
    • saving images (JPG, PNG) and binary Jmol states (JMOL, PNGJ, ZIP)
    • retrieving RCSB REST XML data services ("load =xxxxxxx?")
    • enabling cross-platform AJAX in MSIE (RCSB, NCI, PubChem)
    • reading binary files synchronously (as in the load command, or when using var x = load(...) in a Jmol script) in some browsers.

Details: jsmol.php will be called if you request a binary format file (gz, zip, pse, etc.) from Safari, Chrome, or MSIE. Those browsers can't transfer that sort of file directly and need a server-side piece. But they will have to have that on your server (the same where the webpage is).

In addition, jsmol.php processes image creation requests and "turns around" binary data such as .jpg and .zip files created by JSmol on the page and simply returns it. For this functionality, jsmol.php could be anywhere, including the default location at StOlaf.

• j2s The suite of JavaScript libraries needed for JSmol/HTML5 modality.
• js Non-packed copies of JavaScript libraries needed for JSmol (most of these files are already included in packed form within JSmol.min.js, see above):
  • j2sjmol.js Required interface to the Jmol and java classes (translated into JavaScript and compressed using the Google Closure Compiler.)
  • JSmol.js Primary JSmol library, with private methods for creating and interacting with canvases
  • JSmolApi.js All public user-intended interface functions
  • JSmolApplet.js Required applet prototypes for use with Java or HTML5
  • JSmolControls.js Required only if any buttons or links or other input methods will be used
  • JSmolCore.js Primary JSmol library, with private methods for file loading, primarily
  • JSmolJSV.js Needed only for using the JSpecView object
  • ...and others (undocumented)
  • core (undocumented)
• Some tens of sample pages (htm files) included for your convenience but not required for functionality; among them:
  • supersimple.htm, simple.htm, jsmol.htm, test2.htm, test3.htm , and cover.htm are demonstration/example pages
  • data, images contain files used by the above demo pages
• flot, jcse, jsme, etc. are for specific applications (advanced)

Note: The applet folder has been removed from the distribution since the use of Java applets long deprecated in web browsers.

Specific browser considerations

Access to local files

If you want to load your pages from local disk, some limitations apply depending on the browser. Please see Troubleshooting/Local Files.

Chrome/Windows

Saving files from JSmol/HTML5 will work without accessing jsmol.php file, but any filename and extension that was provided by script will be zapped by Chrome, which insists on offering to save the file with the name "download.txt".

Contributors

AngelHerraez