Jmol JavaScript Object/Installation

From Jmol
Revision as of 15:58, 18 April 2024 by AngelHerraez (talk | contribs) (moving to this new independent page what was a section in Jmol_JavaScript_Object and updating info for Jmol 16)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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, File icon.gifJmol-xxx.zip, that contains File icon.gifJmol.jar (the Jmol application) and a File icon.gifjsmol.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 File icon.gifJSmol.min.js and Folder icon.gifj2s (A total of about 36 MB, but only those parts actually needed in each occasion will be downloaded to the client computer).
  • Folder icon.gifjs is only important if you want to experiment with the code (advanced).

In detail

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

  • Major files:
    • File icon.gifJSmol.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)
      • File icon.gifJSmol.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 File icon.gifJSmoljQuery.js internal component.
    • File icon.gifJSmol.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.
      • File icon.gifJSmol.lite.nojq.js An equivalent version that does not include jQuery (useful if you are already using jQuery in your page).
    • File icon.gifJSmol.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.
  • Folder icon.gifphp
    • File icon.gifjsmol.php or File icon.gifjsmol2.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 File icon.gif.jpg and File icon.gif.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.
  • Folder icon.gifj2s The suite of JavaScript libraries needed for JSmol/HTML5 modality.
  • Folder icon.gifjs Non-packed copies of JavaScript libraries needed for JSmol (most of these files are already included in packed form within File icon.gifJSmol.min.js, see above):
    • File icon.gifj2sjmol.js Required interface to the Jmol and java classes (translated into JavaScript and compressed using the Google Closure Compiler.)
    • File icon.gifJSmol.js Primary JSmol library, with private methods for creating and interacting with canvases
    • File icon.gifJSmolApi.js All public user-intended interface functions
    • File icon.gifJSmolApplet.js Required applet prototypes for use with Java or HTML5
    • File icon.gifJSmolControls.js Required only if any buttons or links or other input methods will be used
    • File icon.gifJSmolCore.js Primary JSmol library, with private methods for file loading, primarily
    • File icon.gifJSmolJSV.js Needed only for using the JSpecView object
    • ...and others (undocumented)
    • Folder icon.gifcore (undocumented)
  • Some tens of sample pages (htm files) included for your convenience but not required for functionality; among them:
    • File icon.gifsupersimple.htm, File icon.gifsimple.htm, File icon.gifjsmol.htm, File icon.giftest2.htm, File icon.giftest3.htm , and File icon.gifcover.htm are demonstration/example pages
    • Folder icon.gifdata, Folder icon.gifimages contain files used by the above demo pages
  • Folder icon.gifflot, Folder icon.gifjcse, Folder icon.gifjsme, etc. are for specific applications (advanced)
Note: The Folder icon.gifapplet 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 File icon.gifjsmol.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