Jmol JavaScript Object - Revision history

AngelHerraez: updates to remove methods for Java applet

2025-08-18T18:19:49Z

updates to remove methods for Java applet

AngelHerraez: updates to remove methods for Java applet

2025-08-18T17:52:27Z

updates to remove methods for Java applet

AngelHerraez: installation instructions moved to separate page and updated to Jmol 16

2024-04-18T16:00:09Z

installation instructions moved to separate page and updated to Jmol 16

AngelHerraez: "idioma" folder is now deprecated

2024-02-17T22:49:57Z

"idioma" folder is now deprecated

AngelHerraez: 'idioma' folder is no longer used

2024-02-07T20:09:02Z

'idioma' folder is no longer used

AngelHerraez: applet JAR files no longer included in recent versions

2021-09-30T18:48:15Z

applet JAR files no longer included in recent versions

Ceroni: /* Setting parameters */

2021-07-04T21:36:31Z

‎Setting parameters

AngelHerraez: Converting legacy web pages -> new subpage

2019-11-20T10:33:29Z

Converting legacy web pages -> new subpage

AngelHerraez: /* Setting parameters */

2019-11-12T10:54:28Z

‎Setting parameters

AngelHerraez: update of descriptions (mostly, Java left behind)

2019-10-27T16:45:59Z

update of descriptions (mostly, Java left behind)

@@ Line 1: / Line 1: @@
 {{Lang:Jmol JavaScript Object}}
-== JSmol, the Jmol JavaScript Object ==
+== Introduction and a little history ==
 <div style="float:right; margin-left:1em;">
 __TOC__
@@ Line 19: / Line 21: @@
 * the '''JSME HTML5 object''', so 3D models can be generated by a page visitor using simple chemical 2D drawing (see [[Jmol_JavaScript_Object/JME|more details]])
-'''JSmol''' is fully compatible with [http://jquery.com 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.
+'''JSmol''' is fully compatible with [http://jquery.com jQuery] 1.9 or later. The library has been W3C and XHTML validated.
 ===Main features of JSmol ===
 <table class="wikitable">
 <tr>
-<th>Non-Java options</th><td>Options for HTML5-only and optionally Java and HTML5/WebGL. 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.</td>
+<th>Non-Java options</th><td>Options for HTML5-only and optionally HTML5/WebGL. Includes a variety of options, such as initial "deferred mode", where an initial image is displayed, with a click on the image or link on the page initiating 3D model panel, and "image+loading" mode, in which case the 3D model is loading behind the scenes while an initial image is displayed.</td>
 </tr>
 <tr>
 <th>Library files</th>
-<td>Requires at a minimum {{file|JSmol.min.js}} as well as {{folder|j2s}}; for internationalized interface, also {{folder|idioma}}. Also optionally {{folder|java}}.</td>
+<td>Requires at a minimum {{file|JSmol.min.js}} as well as {{folder|j2s}}.</td>
 </tr>
 <tr>
@@ Line 36: / Line 38: @@
 <tr>
 <th>JavaScript prototypes</th>
-<td>The object you create using <code>Jmol.getApplet()</code> or <code>Jmol.getAppletHtml()</code> is a JavaScript object that is a subclass of <code>Jmol._Applet</code>. When you use <code>Jmol.getApplet()</code>, you get a reference to a JavaScript object, not the applet/canvas itself. The applet or canvas is wrapped in a set of <code>div</code> elements, allowing a richer diversity of options.</td>
+<td>The object you create using <code>Jmol.getApplet()</code> or <code>Jmol.getAppletHtml()</code> is a JavaScript object that is a subclass of <code>Jmol._Applet</code>. When you use <code>Jmol.getApplet()</code>, you get a reference to a JavaScript object, not the canvas itself. The canvas is wrapped in a set of <code>div</code> elements, allowing a richer diversity of options.</td>
 </tr>
 <tr>
@@ Line 48: / Line 50: @@
 <tr>
 <th>Scripting</th>
-<td>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.</td>
+<td>JSmol provides the same full complement of scripting that Jmol offers. JSmol accepts script commands immediately, before or during canvas creation on the page, caching them until JSmol is ready to accept them.</td>
 </tr>
 </table>
@@ Line 64: / Line 66: @@
 ===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:
+* Using local files (i.e. not in a web server) is not supported on some browsers due to their security policies. For details, see [[JSmol Deployment Local‎‎]] and [[Troubleshooting/Applet‎]].
 * 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).
@@ Line 95: / Line 93: @@
 ==== 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.)
+For binary file reading to be compatible with Chrome Edge (and Chromium-based browsers), 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]].
@@ Line 113: / Line 111: @@
 ==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''.
+JSmol makes strong use of the HTML5 features. Therefore, it is only compatible with modern web browsers.
 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 [[wikipedia:Byte_order_mark#UTF-8|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).
+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.
 Therefore your html documents should start as:
@@ Line 131: / Line 129: @@
 <code><script type="text/javascript" src="JSmol.min.js"></script></code>
-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).
+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 at least to 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 JSmol depends upon whether the page is loaded using "file:" or "http:"
 :: <code>http:</code> 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.
-:: <code>file:</code> all files should be on the local machine within or under the folder containing the {{file|.html}} page.
+:: <code>file:</code> all files should be on the local machine.
 ==== Lightweight JSmol ====
@@ Line 147: / Line 144: @@
 * [[Jmol_JavaScript_Object/JSV|Integration with JSpecView]], a viewer for spectral data.
 * [[Jmol_JavaScript_Object/WebGL|WebGL modality]] to render the 3D model using a combination of HTML5 and WebGL graphics (in compatible systems)
 === Setting parameters ===

@@ Line 156: / Line 156: @@
 This will create a <tt>myJmol</tt> global variable in JavaScript that holds the JSmol 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 can be specified.
+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 can be specified.
 The regular call to create a JSmol object with specified characteristics is
@@ Line 164: / Line 164: @@
 Once <code>Info</code> has been defined, you create and insert the JSmol object in the page using this:
-<code>'''Jmol'''.getApplet("myJmol", Info)</code>
+<code>Jmol.getApplet("myJmol", Info)</code>
 :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 JSmol object that is being created. You may wish to have two JSmols 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 JSmol object constructor.
@@ Line 171: / Line 171: @@
 <pre>
 var Info = {
    height: 300,
    width: 300,
@@ Line 177: / Line 176: @@
    use: "HTML5",
    j2sPath: "j2s",
-   serverURL: "php/jsmol.php",
+   serverURL: "php/jsmol.php"
 };
@@ Line 190: / Line 189: @@
 If you want more control, keep reading.
-<span style="font-size:1.2em;">
+Major parameters included in the <code>Info</code> variable are given below, together with their default values.
-A '''[[Jmol_JavaScript_Object/Info|detailed explanation]] of the parameters''' included in the <code>Info</code> variable
-</span>
+For full documentation, please visit
-is available in a separate page, while the major ones and their default values are given below:
+<span style="background-color:#FFFF66; font-size:1.2em; font-weight:bold;">
 <pre>
 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%")
+   height: 300,      // pixels (it may be in percent, like "100%", but see note below)
    width: 300,
-   use: "HTML5",     // "HTML5" or "Java" (case-insensitive)
+   use: "HTML5",     // "HTML5" or "WebGL" (case-insensitive)
-   j2sPath: "j2s",          // only used in the HTML5 modality
+   j2sPath: "j2s",
    serverURL: "php/jsmol.php",  // this is not applied by default; you should set this value explicitly
    src: null,          // file to load
@@ Line 213: / Line 211: @@
 };
 </pre>
 ==== Setting parameters from the URL ====
 ''Jmol 14.0 or later''
-Some values in the <tt>Info</tt> 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.
+Some values in the <tt>Info</tt> 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 someone else's pages.
 The settable options affect
-* what modality of J(S)mol to use, either Java or HTML5
+* what modality of J(S)mol to use, either HTML5 or WebGL.
-* 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 JSmol files from some other location (url)
-* whether to get the JmolApplet files from some other location (url)
+* whether to get the JavaScript files that build the JSmol 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. <code>?parameter1=value1&parameter2=value2&...etc.</code>
@@ Line 230: / Line 228: @@
 <pre>
 any.htm?_USE=html5
-any.htm?_USE=java
+any.htm?_USE=WebGL
 any.htm?_J2S=http://some.url.com/some/jsmol/j2s
 any.htm?_USE=html5&_J2S=http://some.url.com/some/jsmol/j2s
 </pre>

@@ Line 109: / Line 109: @@
 ==Installation==
+See [[Jmol JavaScript Object/Installation]]
 ==Initialization==

@@ Line 119: / Line 119: @@
 ====In summary====
 * 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).
 * {{folder|js}} is only important if you want to experiment with the code (advanced).
 ====In detail====
@@ Line 141: / Line 141: @@
 :: In addition, jsmol.php processes image creation requests and "turns around" binary data such as {{file|.jpg}} and {{file|.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|j2s}} The suite of JavaScript libraries needed for JSmol/HTML5 modality.
 * {{folder|js}} Non-packed copies of JavaScript libraries needed for the Jmol object (most of these files are already included in packed form within {{file|JSmol.min.js}}, see above):
@@ Line 156: / Line 155: @@
 ** {{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|flot}},  {{folder|inchi}}, {{folder|jcse}}, {{folder|jsme}}, etc. are for specific applications (advanced)
 * {{folder|applet}} The files for the Java modality (JmolApplet), the same that have been used for Jmol in previous versions.

@@ Line 141: / Line 141: @@
 :: In addition, jsmol.php processes image creation requests and "turns around" binary data such as {{file|.jpg}} and {{file|.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|idioma}} Support for the interface in languages other than US English.
+* {{folder|idioma}} Support for the interface in languages other than US English. ''Note:'' in recent versions, this folder does not exist any more; the functionality is now in files inside the {{folder|j2s}} folder.
 * {{folder|j2s}} The suite of JavaScript libraries needed for JSmol/HTML5 modality.
 * {{folder|js}} Non-packed copies of JavaScript libraries needed for the Jmol object (most of these files are already included in packed form within {{file|JSmol.min.js}}, see above):

@@ Line 157: / Line 157: @@
 * {{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)
+* {{folder|applet}} The files for the Java modality (JmolApplet), the same that have been used for Jmol in previous versions.
-{{folder|applet}} The files for the Java modality (JmolApplet), the same that have been used for Jmol in previous versions.
+**  {{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.)
 === Specific browser considerations ===

@@ Line 104: / Line 104: @@
 In Chrome and also other browsers, you may overcome problems with loading '''''local''''' binary files by running pages through a local web server.
-=== Converting pages from Jmol to JSmol ===
+=== Converting legacy web pages to JSmol ===
-* Switching from {{file|Jmol.js}} to {{file|JSmol.min.js}}
+It is not hard to convert pages that used the Jmol Applet and the <code>Jmol.js</code> library to use the HTML5 versions of JSmol. See [[Jmol JavaScript Object/Legacy|more details]].
 ==Installation==

@@ Line 1: / Line 1: @@
 {{Lang:Jmol JavaScript Object}}
-== The Jmol JavaScript Object (JSmol) ==
+== JSmol, the Jmol JavaScript Object ==
 <div style="float:right; margin-left:1em;">
 __TOC__
@@ Line 219: / Line 219: @@
 ** {{file|JSmolCore.js}} Primary JSmol library, with private methods for file loading, primarily
 <!--** {{file|JSmoljQuery.js}} A version of jQuery tweaked to allow synchronous binary file transfer and use with MSIE and Safari-->
-** {{file|JSmolJSV.js}} Needed only for [[Jmol_JavaScript_Object/JSV|using the JSpecView applet]]
+** {{file|JSmolJSV.js}} Needed only for [[Jmol_JavaScript_Object/JSV|using the JSpecView object]]
 * A few sample pages and files, included for your convenience but not required for functionality:
 ** {{file|supersimple.htm}}, {{file|simple.htm}}, {{file|jsmol.htm}}, {{file|test2.htm}}, {{file|test3.htm}} , and {{file|cover.htm}} are demonstration/example pages
@@ Line 301: / Line 301: @@
 Once <code>Info</code> has been defined, you create and insert the JSmol object in the page using this:
-<code>Jmol.getApplet("myJmol", Info)</code>
+<code>'''Jmol'''.getApplet("myJmol", Info)</code>
-: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 JSmol object that is being created. You may wish to have two JSmols 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 JSmol 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 JSmol object that is being created. You may wish to have two JSmols 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 JSmol object constructor.
 For a start, you may just copy and then adapt this simple example:
@@ Line 319: / Line 319: @@
 Jmol.getApplet("myJmol", Info);
 </pre>
 If you want more control, keep reading.
@@ Line 370: / Line 376: @@
 == Functions for Jmol JavaScript Object ==
-Please see [[Jmol_JavaScript_Object/Functions]].
+Please see [[Jmol_JavaScript_Object/Functions]] for details about:
 * Functions for creation or display of Jmol Objects
 * Functions for creating controls