The heart of JSmol is the The Jmol JavaScript object, (<code>window.Jmol</code>), which includes a set of JavaScript functions and utilities. The initial Jmol object was developed by Bob Hanson and Paul Pillot in early 2012. It was folded into '''JSmol''' later that year. The library {{file| JSmol.min.js}} provides this object and supersedes the [{{Website}}jslibrary/ Jmol.js JavaScript library] formerly used exclusively with the Jmol Java applet, allowing a cleaner, more efficient way to interact with Jmol on a web page, and abstracting the visualization of a molecular model so that the Java applet can be seamlessly and selectively replaced by a non-Java HTML5 canvas element (which might not even be Jmol).

+

The heart of JSmol is the Jmol JavaScript object, (<code>window.Jmol</code>), which includes a set of JavaScript functions and utilities. The initial Jmol object was developed by Bob Hanson and Paul Pillot in early 2012. It was folded into '''JSmol''' later that year. The library {{file| JSmol.min.js}} provides this object and supersedes the [{{Website}}jslibrary/ Jmol.js JavaScript library] formerly used exclusively with the Jmol Java applet, allowing a cleaner, more efficient way to interact with Jmol on a web page, and abstracting the visualization of a molecular model so that the Java applet can be seamlessly and selectively replaced by a non-Java HTML5 canvas element (which might not even be Jmol).

Using '''JSmol''', a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using '''a Jmol applet surrogate''' while still implementing the Jmol Java applet on traditional platforms. The wide variety of options available allows Jmol's functionality on all such devices, and there should be no need to ever see a message "Sorry, you don't have Java installed...."

Using '''JSmol''', a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using '''a Jmol applet surrogate''' while still implementing the Jmol Java applet on traditional platforms. The wide variety of options available allows Jmol's functionality on all such devices, and there should be no need to ever see a message "Sorry, you don't have Java installed...."

Line 20:

Line 22:

<tr>

<tr>

<th>Library Files</th>

<th>Library Files</th>

−

<td>Requires at a minimum, {{file|JSmol.min.js}} and {{folder|j2s}} and/or {{folder|java}}.</td>

+

<td>Requires at a minimum {{file|JSmol.min.js}} as well as either {{folder|j2s}}, {{folder|java}} or both.</td>

</tr>

</tr>

<tr>

<tr>

<th>JavaScript Objects</th>

<th>JavaScript Objects</th>

−

<td>Creates a single JavaScript Object, <code>Jmol</code>, which includes a set of functions and internal objects such as <code>Jmol._Applet</code>, <code>Jmol._Image</code>, and <code>Jmol.controls</code>.</td>

+

<td>Creates a single JavaScript object, <code>Jmol</code>, which includes a set of functions and internal objects such as <code>Jmol._Applet</code>, <code>Jmol._Image</code>, and <code>Jmol.controls</code>.</td>

</tr>

</tr>

<tr>

<tr>

Line 48:

Line 50:

[[Image:JSmol_logo13.png]]

[[Image:JSmol_logo13.png]]

</div>

</div>

−

'''JSmol''' is the name for the HTML5 canvas version of the Jmol applet. '''JSmol''' opens up the use of Jmol in PC, Mac, and Linux systems without Java installed or with Java disabled, as well as tablets and phones (both iOS and Android). No hardware-based graphics acceleration is used, allowing '''JSmol''' to run in any web browser that supports HTML5 standards. JSmol runs entirely in the client, needing no server technologies for most of its operation. (Reading binary files in some browsers and saving images and Jmol states in all browsers do require a server-side PHP script.)

'''JSmol''' is the name for the HTML5 canvas version of the Jmol applet. '''JSmol''' opens up the use of Jmol in PC, Mac, and Linux systems without Java installed or with Java disabled, as well as tablets and phones (both iOS and Android). No hardware-based graphics acceleration is used, allowing '''JSmol''' to run in any web browser that supports HTML5 standards. JSmol runs entirely in the client, needing no server technologies for most of its operation. (Reading binary files in some browsers and saving images and Jmol states in all browsers do require a server-side PHP script.)

Line 61:

Line 62:

** MSIE allows access to local files only if they are not binary.

** MSIE allows access to local files only if they are not binary.

** Chrome allows access only when Chrome has been started using a special command-line flag (<code>chrome.exe --allow-file-access-from-files</code>).

** Chrome allows access only when Chrome has been started using a special command-line flag (<code>chrome.exe --allow-file-access-from-files</code>).

* Opening binary files (e.g Spartan files, gzipped files, {{file|pngj}} files): they can be read but must be identified as such in their file name (see below).

* Opening binary files (e.g Spartan files, gzipped files, {{file|pngj}} files): they can be read but must be identified as such in their file name (see below).

* Writing of {{file|jpg}}, {{file|png}} and {{file|pngj}} (png+zip) data is fully supported, but delivering it to a user may require a server-side piece. (See also [[Recycling_Corner#Exporting_an_image_from_the_applet|Exporting an image]] for alternatives).

* Writing of {{file|jpg}}, {{file|png}} and {{file|pngj}} (png+zip) data is fully supported, but delivering it to a user may require a server-side piece. (See also [[Recycling_Corner#Exporting_an_image_from_the_applet|Exporting an image]] for alternatives).

* The Jmol <code>prompt</code> command does not allow more than a simple JavaScript-like response in the HTML5 version.

* The Jmol <code>prompt</code> command does not allow more than a simple JavaScript-like response in the HTML5 version.

−

* The WebGL modality of JSmol has not been fully developed and feature support is limited.

+

* The [[Jmol_JavaScript_Object/WebGL|WebGL modality]] of JSmol has not been fully developed and feature support is limited.

=== Reading binary files ===

=== Reading binary files ===

−

Jmol (Java) can open a file and then determine whether the file is binary or not. JSmol (JavaScript) is different, because the AJAX transport mechanism is different for binary and nonbinary files. Thus, JSmol must determine whether a file is binary or not ''prior'' to its loading. JSmol does this by inspection of the file name. JSmol will switch to binary mode for files with any of the following in their file name:

+

Jmol (Java) can open a file and then determine whether the file is binary or not. JSmol (JavaScript) is different, because the AJAX transport mechanism is different for binary and nonbinary files. Thus, JSmol must determine whether a file is binary or not ''prior'' to its loading.

+

+

==== File names ====

+

JSmol will determine whether a file is binary or not --before loading it-- by inspection of the file name. JSmol will switch to binary mode for files with any of the following in their file name:

{{file|.bin}}

{{file|.bin}}

{{file|.gz}}

{{file|.gz}}

Line 82:

Line 86:

These "extensions" can appear anywhere in a file name to trigger the binary access mode. So, for example, if you rename any file to include <code>.bin</code> anywhere in its name, that will instruct JSmol to read it as a binary file.

These "extensions" can appear anywhere in a file name to trigger the binary access mode. So, for example, if you rename any file to include <code>.bin</code> anywhere in its name, that will instruct JSmol to read it as a binary file.

−

For binary file reading to be compatible with Chrome and MSIE, you will need to have a base64 server-side piece that will convert the binary data to <code>BASE64</code> format. This is because only Firefox allows clean (reliable) synchronous binary file transfer. (And, so far, we have not figured out how to move all the file loading in Jmol to a fully asynchronous mode.) The [{{StOlaf}}jsmol/jsmol.htm demo pages] use the {{file|jsmol.php}} script that is included in the JSmol distribution (see below), which does that and considerably more. If your page visitors need to read binary files, place a copy of {{file|jsmol.php}} on your server and point to it using the '''serverURL''' item of the Info array.

+

:''Advanced'': If you need a different extension to be read as binary, and cannot change the file names to include one of the default extensions, it is possible to extend the set using this code in your Javascript after the Jmol object has being initialized: <code>Jmol._binaryTypes.push('.myExtension');</code>

+

+

==== Browser behaviour ====

+

For binary file reading to be compatible with Chrome and MSIE, you will need to have a base64 server-side piece that will convert the binary data to <code>BASE64</code> format. This is because only Firefox allows clean (reliable) synchronous binary file transfer. (And, so far, we have not figured out how to move all the file loading in Jmol to a fully asynchronous mode.)

+

+

If your page visitors need to read binary files, place a copy of the {{file|jsmol.php}} file that is included in the JSmol distribution (see below) on your server and point to it using the [[Jmol_JavaScript_Object/Info#Files_and_paths|'''serverURL''' item of the Info array]].

+

As an example, the [{{StOlaf}}jsmol/jsmol.htm demo pages] use this approach.

+

+

For that to work, your server must support PHP. Otherwise, you might "borrow" by pointing to the {{file|jsmol.php}} file in another server that can run PHP (please, ask the owner of that server).

+

+

In Chrome, some problems with loading '''''local''''' binary files may be overcome by using a parameter in the command that opens the browser:

Full releases of J(S)mol may be obtained at [http://sourceforge.net/projects/jmol/files/ the Jmol Project page]. The most up-to-date, development, version can be found as [{{StOlaf}}zip/ St. Olaf].

Full releases of J(S)mol may be obtained at [http://sourceforge.net/projects/jmol/files/ the Jmol Project page]. The most up-to-date, development, version can be found as [{{StOlaf}}zip/ St. Olaf].

−

The distribution is a zipfile, {{file|Jmol-xxx.zip}}, that contains {{file|Jmol.jar}} (the Jmol application) and a {{file|jsmol.zip}} file which in turn contains the whole set of files potentially needed for deploying the Jmol Object in a webpage, either in the Jmol/Java or JSmol/HTML5 modalities. Note that usually you don't need all those files, as described below.

+

The distribution is a zipfile, {{file|Jmol-xxx.zip}}, that contains {{file|Jmol.jar}} (the Jmol application) and a {{file|jsmol.zip}} file which in turn contains the whole set of files potentially needed for deploying the Jmol Object in a webpage, either in the Jmol/Java or JSmol/HTML5 modalities. Note that usually you don't need all those files for operation, as described below.

−

In summary:

+

====In summary====

−

* For pages that use the HTML5 modality of JSmol, you just need {{file|JSmol.min.js}} and {{folder|j2s}} (A total of 12.6 MB, but only those parts actually needed will be downloaded to the client computer).

+

* For pages that use the HTML5 modality of JSmol, you just need {{file|JSmol.min.js}} and {{folder|j2s}} (A total of 21.3 MB, but only those parts actually needed in each occasion will be downloaded to the client computer).

−

* For pages that use only the Jmol Java applet modality, you just need {{file|JSmol.min.js}} and {{folder|java}} (A total of 7.9 MB, but may be reduced to 2.2 MB for a single set of signed or unsigned applet files, of which only those parts actually needed will be downloaded to the client computer).

+

* For pages that use only the Java modality (Jmol applet or Jmol_S), you just need {{file|JSmol.min.js}} and {{folder|java}} (A total of 17 MB, but may be reduced to 4 MB for a single set of signed or unsigned applet files, of which only those parts actually needed in each occasion will be downloaded to the client computer).

−

* {{folder|js}} is only important if you want to use the (experimental, not fully functional) WebGL version of JSmol. Specifically, you need {{file|js/JSmolGLmol.js}} and {{file|js/JSmolThree.js}} (which are not minimized), since those two libraries are not included in {{file|JSmol.min.js}}.

+

* Note that, even if you don't intend to use both the HTML5 and Java modalities, you should as a courtesy to your visitors try to include in your web server both {{folder|j2s}} and {{folder|java}}. If they are available, each user may force one or the other modality by adding options in the url line.

+

* {{folder|idioma}} is important for users of languages other than US English to see the Jmol interface, menu and messages in their own language. It must be located as a sibling folder of {{folder|j2s}} (or {{folder|java}} if you use the Java modality).

+

* {{folder|js}} is only important if you want to experiment with the code (advanced).

−

In detail:

+

====In detail====

{{file|jsmol.zip}} (which is included inside the Jmol distribution zip file) contains these files and folders:

{{file|jsmol.zip}} (which is included inside the Jmol distribution zip file) contains these files and folders:

* Major files:

* Major files:

** {{file|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)

** {{file|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)

−

*** {{file|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 {{file|JSmoljQuery.js}}.

+

*** {{file|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 {{file|JSmoljQuery.js}} internal component. ''Note'': if you use this, you might need to also include in your page a call to the jQuery-UI library.

** {{file|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.

** {{file|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.

*** {{file|JSmol.lite.nojq.js}} An equivalent version that does not include jQuery (useful if you are already using jQuery in your page).

*** {{file|JSmol.lite.nojq.js}} An equivalent version that does not include jQuery (useful if you are already using jQuery in your page).

+

** {{file|JSmol.GLmol.min.js}} is a supplementary library addressed at using a [[Jmol_JavaScript_Object/WebGL|WebGL modality]] of the Jmol Object. Note that this is experimental, not under active development, and not fully functional.

* {{folder|php}}

* {{folder|php}}

Line 191:

Line 210:

** {{file|JmolApplet.jar}} or {{file|JmolAppletSigned.jar}} or {{file|JmolApplet0*.jar}} or {{file|JmolAppletSigned0*.jar}}

** {{file|JmolApplet.jar}} or {{file|JmolAppletSigned.jar}} or {{file|JmolApplet0*.jar}} or {{file|JmolAppletSigned0*.jar}}

:: (That is, a set of files, where the * stands for several suffixes. You may need to read about [[Jmol_Applet#Unsigned_vs._Signed_Applet_.26_Data_Access|signed vs. unsigned applet]] if you are unfamiliar with the Jmol jar files.)

:: (That is, a set of files, where the * stands for several suffixes. You may need to read about [[Jmol_Applet#Unsigned_vs._Signed_Applet_.26_Data_Access|signed vs. unsigned applet]] if you are unfamiliar with the Jmol jar files.)

** {{folder|data}}, {{folder|images}} Files used by the above demo pages

−

* {{folder|make}} and {{folder|test}} are for developers only. (The {{folder|make}} directory includes the Google Closure Compiler used to create {{file|Jsmol.min.js}}.)

+

* {{folder|make}} and {{folder|test}} are for developers only. (The {{folder|make}} directory includes the Google Closure Compiler used to create {{file|Jsmol.min.js}}.) {{folder|flot}}, {{folder|inchi}}, {{folder|jcse}}, {{folder|jsme}}, etc. are for specific applications (advanced)

=== Specific browser considerations ===

=== Specific browser considerations ===

Line 259:

Line 277:

==== Lightweight JSmol ====

==== Lightweight JSmol ====

−

There is an alternative version of Jmol object that, using the HTML5 canvas like JSmol, loads very fast while offering minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at smartphones and such systems with limited resources. To use this, instead of invoking {{file|JSmol.min.js}} you call:

+

There is an alternative version of Jmol object that, using the HTML5 canvas like JSmol, loads very fast while offering minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at smartphones and such systems with limited resources.

* [[Jmol_JavaScript_Object/JSV|Integration with JSpecView]], a Java viewer for spectral data.

* [[Jmol_JavaScript_Object/JSV|Integration with JSpecView]], a Java viewer for spectral data.

−

* [[Jmol_JavaScript_Object/GLmol|GLmol option]] to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems) (does not use Java)

+

* [[Jmol_JavaScript_Object/WebGL|WebGL modality]] to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems) (does not use Java)

* [[Jmol_JavaScript_Object/ChemDoodle|ChemDoodle option]] to render the 3D model using ChemDoodle (does not use Java)

* [[Jmol_JavaScript_Object/ChemDoodle|ChemDoodle option]] to render the 3D model using ChemDoodle (does not use Java)

=== Setting parameters ===

=== Setting parameters ===

+

The essential and minimal call to create a Jmol object (as JSmol, the non-Java modality) is simply:

−

All of the initialization parameters supported in Jmol.js can be implemented in JSmol. However, the method of indicating variables is different. The essential call to create a Jmol object (an applet or an alternative non-Java viewer) is simply:

+

<code>Jmol.getApplet("myJmol")</code>

+

+

This will create a <tt>myJmol</tt> global variable in JavaScript that holds the Jmol object and is also the unique ID for that object in all functions and methods described below. ''Note that this simplest syntax will only work when the html file is located in the root JSmol folder.''

+

+

However, in most situations you will want to customize some aspects, like the size of the object and the file paths. All of the initialization parameters that were supported in Jmol.js can be implemented in JSmol. However, the method of indicating variables is different.

+

+

The regular call to create a Jmol object (an applet or an alternative non-Java viewer) with specified characteristics is

+

to define an <code>Info</code> variable, which is an associative array (a set of key+value pairs) that indicates all the desired characteristics of the Jmol object.

+

The Jmol-JSO library will provide a default <code>Info</code> variable, so you only need to specify those keys which values you want to customize.

+

+

Once <code>Info</code> has been defined, you create and insert the Jmol object in the page using this:

<code>Jmol.getApplet("myJmol", Info)</code>

<code>Jmol.getApplet("myJmol", Info)</code>

−

This will create a <tt>myJmol</tt> global variable in JavaScript that holds the Jmol object and is also the unique ID for that object in all functions and methods described below.

:Note that <tt>myJmol</tt> and <tt>Info</tt> are user-defined variables and may hence have any name you wish. <tt>myJmol</tt> becomes in fact the identifier of the particular Jmol object that is being created. You may wish to have two Jmols in your page and call them e.g. <tt>jmolA</tt> and <tt>jmolB</tt>, and use for them the same set of parameters <tt>Info</tt>, or use two different sets named e.g. <tt>InfoA</tt> and <tt>InfoB</tt>. In contrast, <tt>Jmol</tt> (right at the beginning) must be written as such, since it is the internal name and identification of the unique Jmol object constructor.

:Note that <tt>myJmol</tt> and <tt>Info</tt> are user-defined variables and may hence have any name you wish. <tt>myJmol</tt> becomes in fact the identifier of the particular Jmol object that is being created. You may wish to have two Jmols in your page and call them e.g. <tt>jmolA</tt> and <tt>jmolB</tt>, and use for them the same set of parameters <tt>Info</tt>, or use two different sets named e.g. <tt>InfoA</tt> and <tt>InfoB</tt>. In contrast, <tt>Jmol</tt> (right at the beginning) must be written as such, since it is the internal name and identification of the unique Jmol object constructor.

−

<code>Info</code> is an associative array (a set of key+value pairs) indicating all the desired characteristics of the Jmol object.

+

For a start, you may just copy and then adapt this simple example:

−

A '''[[Jmol_JavaScript_Object/Info|detailed explanation]] of the parameters''' of the <code>Info</code> variable is available in a separate page, while the major ones and their default values are given below:

+

<pre>

+

var Info = {

+

color: "#FFFFFF",

+

height: 300,

+

width: 300,

+

script: "load $caffeine",

+

use: "HTML5",

+

j2sPath: "j2s",

+

jarPath: "java",

+

jarFile: "JmolAppletSigned0.jar",

+

isSigned: true,

+

serverURL: "php/jsmol.php",

+

disableInitialConsole: true

+

};

+

+

Jmol.getApplet("myJmol", Info);

+

</pre>

+

If you want more control, keep reading.

+

+

A '''[[Jmol_JavaScript_Object/Info|detailed explanation]] of the parameters''' included in the <code>Info</code> variable is available in a separate page, while the major ones and their default values are given below:

The Jmol JavaScript Object (JSmol)

The heart of JSmol is the Jmol JavaScript object, (window.Jmol), which includes a set of JavaScript functions and utilities. The initial Jmol object was developed by Bob Hanson and Paul Pillot in early 2012. It was folded into JSmol later that year. The library JSmol.min.js provides this object and supersedes the Jmol.js JavaScript library formerly used exclusively with the Jmol Java applet, allowing a cleaner, more efficient way to interact with Jmol on a web page, and abstracting the visualization of a molecular model so that the Java applet can be seamlessly and selectively replaced by a non-Java HTML5 canvas element (which might not even be Jmol).

Using JSmol, a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using a Jmol applet surrogate while still implementing the Jmol Java applet on traditional platforms. The wide variety of options available allows Jmol's functionality on all such devices, and there should be no need to ever see a message "Sorry, you don't have Java installed...."

the JME Java applet or JSME HTML5 object, so 3D models can be generated by a page visitor using simple chemical 2D drawing (see more details)

JSmol is fully compatible with jQuery 1.9 or 1.10. (jQuery 2.0 does not and for reasons of principle reportedly will never support MSIE running locally using file://, so if you do not need to run your page in MSIE in a local environment, that should be fine. There is a fix for this, however, if you must do that. In that case you must hack jQuery a bit.) The library has been W3C and XHTML validated.

Main features of JSmol

Non-Java Options

Options for Java, HTML5/WebGL, or HTML5-only. Includes a variety of options, such as initial "deferred-applet" mode, where an initial image is displayed, with a click on the image or link on the page initiating applet/canvas 3D modeling, and "image+loading" mode, in which case the 3D model is loading behind the scenes while an initial image is displayed.

Library Files

Requires at a minimum JSmol.min.js as well as either j2s, java or both.

JavaScript Objects

Creates a single JavaScript object, Jmol, which includes a set of functions and internal objects such as Jmol._Applet, Jmol._Image, and Jmol.controls.

JavaScript Prototypes

The object you create using Jmol.getApplet() is a JavaScript object that is a subclass of Jmol._Applet. When you use Jmol.getApplet(), you get a reference to a JavaScript object, not the Java applet/canvas itself. The applet or canvas is wrapped in a set of div elements, allowing a richer diversity of options.

AJAX

JSmol includes methods to easily access cross-platform resources using AJAX provided by jQuery.

REST services

JSmol lets you access keyword search results from RCSB -- for example, a list of all structures that reference caffeine.

Scripting

JSmol provides the same full complement of scripting that Jmol offers. JSmol accepts script commands immediately, before or during applet/canvas creation on the page, caching them until Jmol is ready to accept them.

JSmol

JSmol is the name for the HTML5 canvas version of the Jmol applet. JSmol opens up the use of Jmol in PC, Mac, and Linux systems without Java installed or with Java disabled, as well as tablets and phones (both iOS and Android). No hardware-based graphics acceleration is used, allowing JSmol to run in any web browser that supports HTML5 standards. JSmol runs entirely in the client, needing no server technologies for most of its operation. (Reading binary files in some browsers and saving images and Jmol states in all browsers do require a server-side PHP script.)

JSmol was developed by Bob Hanson, Zhou Renjian, and Takanori Nakane.

JSmol allows rendering, scripting and interaction with the models just as Jmol does, since the source code is shared by both. Note that JSmol is not a different program than Jmol: it is Jmol, just compiled into JavaScript instead of Java (thanks to the Java2Script software).

Current limitations of JSmol

Using local files (i.e. not in a web server) is not supported on some browsers due to their security policies:

Opera allows no access to local files.

MSIE allows access to local files only if they are not binary.

Chrome allows access only when Chrome has been started using a special command-line flag (chrome.exe --allow-file-access-from-files).

Firefox allows access only after setting a special about:config flag (security.fileuri.strict_origin_policy = false).

Opening binary files (e.g Spartan files, gzipped files, pngj files): they can be read but must be identified as such in their file name (see below).

Writing of jpg, png and pngj (png+zip) data is fully supported, but delivering it to a user may require a server-side piece. (See also Exporting an image for alternatives).

The Jmol prompt command does not allow more than a simple JavaScript-like response in the HTML5 version.

The WebGL modality of JSmol has not been fully developed and feature support is limited.

Reading binary files

Jmol (Java) can open a file and then determine whether the file is binary or not. JSmol (JavaScript) is different, because the AJAX transport mechanism is different for binary and nonbinary files. Thus, JSmol must determine whether a file is binary or not prior to its loading.

File names

JSmol will determine whether a file is binary or not --before loading it-- by inspection of the file name. JSmol will switch to binary mode for files with any of the following in their file name:
.bin.gz.zip.jpg.png.jmol.smol.spartan.mrc.pse

These "extensions" can appear anywhere in a file name to trigger the binary access mode. So, for example, if you rename any file to include .bin anywhere in its name, that will instruct JSmol to read it as a binary file.

Advanced: If you need a different extension to be read as binary, and cannot change the file names to include one of the default extensions, it is possible to extend the set using this code in your Javascript after the Jmol object has being initialized: Jmol._binaryTypes.push('.myExtension');

Browser behaviour

For binary file reading to be compatible with Chrome and MSIE, you will need to have a base64 server-side piece that will convert the binary data to BASE64 format. This is because only Firefox allows clean (reliable) synchronous binary file transfer. (And, so far, we have not figured out how to move all the file loading in Jmol to a fully asynchronous mode.)

If your page visitors need to read binary files, place a copy of the jsmol.php file that is included in the JSmol distribution (see below) on your server and point to it using the serverURL item of the Info array.
As an example, the demo pages use this approach.

For that to work, your server must support PHP. Otherwise, you might "borrow" by pointing to the jsmol.php file in another server that can run PHP (please, ask the owner of that server).

In Chrome, some problems with loading local binary files may be overcome by using a parameter in the command that opens the browser:
chrome.exe --allow-file-access-from-files --disable-web-security

Note: this is not allowed in recent versions of Chrome

Converting pages from Jmol to JSmol

It is not hard to convert pages that currently use Jmol to use either the Java or the HTML5 versions of JSmol. The basic sequence includes:

Switching from Jmol.js to JSmol.min.js

Adding the java or j2s folders/directories to your website.

Setting parameters in the Info variable.

Modifying function calls from the format jmolXxxx(..., appletExtension) to Jmol.jmolXxxx(appletID, ...) (see below). Depending upon the magnitude of the problem, you may want to write (but read the next section first!) a set of JavaScript functions that allow you to keep your page source code unchanged. For example, if you use the simplest form of jmolButton, the converting function would be:

Or you can modify your page source code to use the new format. Or, easiest solution, use the 'adapter' library described below.

The main methods formerly implemented in Jmol.js (and more!) have now equivalent functions that can be found in JSmolApi.js
-- also included in the distribution: jsmol.zip > js > JSmolApi.js
You might consider taking this opportunity to find out how jQuery works, if you are not familiar with it, and work more with those functions.

Conversion using the Jmol2.js 'adapter' library

What has been just described (i.e., writing custom functions that allow to keep using the old calls as used with Jmol.js) has been implemented in a special new Jmol2.js 'adapter' library. If you use this, you can leave your existing calls to jmolApplet(), jmolButton(), jmolLink() etc. You just need to:

method A:

method B:

Step 1

In all your pages, add a call to JSmol.min.js

In all your pages, change the existing call to Jmol.js into Jmol2.js

Step 1

Open in a text editor both JSmol.min.js, Jmol2.js and a new blank document. Combine in this document the contents of JSmol.min.js followed by the contents of Jmol2.js. Save this new document as Jmol.js

Do not change your pages, keep the existing call to Jmol.js

Step 2:

Add the JSmol files and folders as appropriate †

Step 2:

Add the JSmol files and folders as appropriate †

(†) That is described in the Installation and Initialization sections of this page.

Open jsmol.zip and extract all the JAR and JNLP files in the jsmol/java directory.

Use the most recent version of Jmol.js that you have, or retrieve it from St. Olaf.

Upgrade your site's Jmol.js and your JAR files with the files you have extracted.

Everything should work as before, but users will see a much kinder, more welcoming warning message the first time they access the new applet. Of course they will still have to give permission for the applet to be run, maybe in several dialogs.

Installation

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

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 the Jmol Object in a webpage, either in the Jmol/Java or JSmol/HTML5 modalities. Note that usually you don't need all those 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 21.3 MB, but only those parts actually needed in each occasion will be downloaded to the client computer).

For pages that use only the Java modality (Jmol applet or Jmol_S), you just need JSmol.min.js and java (A total of 17 MB, but may be reduced to 4 MB for a single set of signed or unsigned applet files, of which only those parts actually needed in each occasion will be downloaded to the client computer).

Note that, even if you don't intend to use both the HTML5 and Java modalities, you should as a courtesy to your visitors try to include in your web server both j2s and java. If they are available, each user may force one or the other modality by adding options in the url line.

idioma is important for users of languages other than US English to see the Jmol interface, menu and messages in their own language. It must be located as a sibling folder of j2s (or java if you use the Java modality).

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 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. Note: if you use this, you might need to also include in your page a call to the jQuery-UI library.

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 is experimental, not under active development, and not fully functional.

php

jsmol.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.

java The files for the Java modality (JmolApplet), the same that have been used for Jmol in previous versions.

JmolApplet.jar or JmolAppletSigned.jar or JmolApplet0*.jar or JmolAppletSigned0*.jar

(That is, a set of files, where the * stands for several suffixes. You may need to read about signed vs. unsigned applet if you are unfamiliar with the Jmol jar files.)

idioma Support for the interface in languages other than US English.

j2s The suite of JavaScript libraries needed for JSmol/HTML5 modality.

js Non-packed copies of JavaScript libraries needed for the Jmol object (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

make and test are for developers only. (The make directory includes the Google Closure Compiler used to create Jsmol.min.js.) flot, inchi, jcse, jsme, etc. are for specific applications (advanced)

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.

MSIE/Windows

Saving files from JSmol/HTML5 requires in Internet Explorer to go through the jsmol.php file, so you will need to have that set-up. The user will get a "Save or Open this file" type of dialog, and the file will be usually saved to the browser's default download folder.

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".

Initialization

Browser issues

JSmol makes strong use of the HTML5 features. Therefore, it is only compatible with modern web browsers. Specifically, Internet Explorer must be version 9 or higher.

In addition, it is important to use a doctype in the header of the html page. The recommended doctype is the simple one, associated to HTML5 standard, as the very first line of your html document.

Also, for full compatibility, particularly for the localization (language translations) of the JSmol pop-up menu, you should declare the charset as UTF-8 and save the html document (and all accessory files) using UTF-8 encoding (usually without BOM, but this needs further confirmation; recent versions of Firefox seem to have problems with non-BOM UTF-8 files, and UTF-8 with BOM looks like a better solution).

Therefore your html documents should start as:

<!DOCTYPE HTML>
<html>
<head>
<meta charset="utf-8">

Loading the library

The web page should have the following in the head section (pointing to appropriate paths if not the same folder as the web page as shown here):

<script type="text/javascript" src="JSmol.min.js"></script>

Please note that there may be restrictions on the folder locations where you can put files for the libraries (js), the page (html), the models and scripts. This is imposed by browser security policies (related to both Java security and AJAX calls in JavaScript) and usually applies only to situations where you are using the pages from local disk (as opposed to a web server).

Successful file access by either the signed or unsigned Java applet or the HTML5 version of Jmol/JSmol depends upon whether the page is loaded using "file:" or "http:"

unsigned applet

http:.jar files must be located in the same folder as data files or in a folder above this.

file: same

signed applet

http: no restrictions

file: same as unsigned applet

HTML5 JSmol

http: all files should be on the host server or on a server set up to deliver cross-domain AJAX using the "Access-Control-Allow-Origin: *" header.

file: all files should be on the local machine within or under the folder containing the .html page.

Lightweight JSmol

There is an alternative version of Jmol object that, using the HTML5 canvas like JSmol, loads very fast while offering minimal functionality (just a simplified ball and stick rendering, no scripting). It is specially aimed at smartphones and such systems with limited resources.

Setting parameters

The essential and minimal call to create a Jmol object (as JSmol, the non-Java modality) is simply:

Jmol.getApplet("myJmol")

This will create a myJmol global variable in JavaScript that holds the Jmol object and is also the unique ID for that object in all functions and methods described below. Note that this simplest syntax will only work when the html file is located in the root JSmol folder.

However, in most situations you will want to customize some aspects, like the size of the object and the file paths. All of the initialization parameters that were supported in Jmol.js can be implemented in JSmol. However, the method of indicating variables is different.

The regular call to create a Jmol object (an applet or an alternative non-Java viewer) with specified characteristics is
to define an Info variable, which is an associative array (a set of key+value pairs) that indicates all the desired characteristics of the Jmol object.
The Jmol-JSO library will provide a default Info variable, so you only need to specify those keys which values you want to customize.

Once Info has been defined, you create and insert the Jmol object in the page using this:

Jmol.getApplet("myJmol", Info)

Note that myJmol and Info are user-defined variables and may hence have any name you wish. myJmol becomes in fact the identifier of the particular Jmol object that is being created. You may wish to have two Jmols in your page and call them e.g. jmolA and jmolB, and use for them the same set of parameters Info, or use two different sets named e.g. InfoA and InfoB. In contrast, Jmol (right at the beginning) must be written as such, since it is the internal name and identification of the unique Jmol object constructor.

A detailed explanation of the parameters included in the Info variable is available in a separate page, while the major ones and their default values are given below:

var Info = {
color: "#FFFFFF", // white background (note this changes legacy default which was black)
height: 300, // pixels (but it may be in percent, like "100%")
width: 300,
use: "HTML5", // "HTML5" or "Java" (case-insensitive)
j2sPath: "j2s", // only used in the HTML5 modality
jarPath: "java", // only used in the Java modality
jarFile: "JmolApplet0.jar", // only used in the Java modality
isSigned: false, // only used in the Java modality
serverURL: "php/jsmol.php", // this is not applied by default; you should set this value explicitly
src: null, // file to load
script: null, // script to run
defaultModel: "", // name or id of a model to be retrieved from a database
addSelectionOptions: false, // to interface with databases
disableInitialConsole: false, // shows a bunch of messages while the object is being built
debug: false
};

Setting parameters from the URL

Jmol 14.0 or later

Some values in the Info variable defined in the page may be overriden by the user, by adding a parameter in the page URL. This may be useful for testing, both own and some else's pages.

The settable options affect

what modality of J(S)mol to use, either Java or HTML5

what kind of applet to use, either 'sandboxed' or 'all-permissions' (new terms, more or less equivalent to the formerly called unsigned and signed applets)

whether to get the JmolApplet files from some other location (url)

whether to get the JavaScript files that build the Jmol Object from some other location (url)

The format for parameters in the url is the standard syntax in so called 'search' part of the url, i.e. ?parameter1=value1&parameter2=value2&...etc.