Jmol JavaScript Object/Info - Revision history

AngelHerraez: /* loadStructCallback */

2026-04-26T17:25:23Z

‎loadStructCallback

AngelHerraez: loadStructCallback with files loaded via dialog

2026-04-26T08:12:30Z

loadStructCallback with files loaded via dialog

AngelHerraez: going back to correct index array numbering with some clarification added

2026-02-27T16:14:55Z

going back to correct index array numbering with some clarification added

EricMartz: /* loadStructCallback */

2026-02-25T22:16:47Z

‎loadStructCallback

EricMartz: /* loadStructCallback */

2026-02-25T22:08:15Z

‎loadStructCallback

EricMartz: /* loadStructCallback */

2026-02-25T22:06:58Z

‎loadStructCallback

EricMartz: /* dragDropCallback */

2026-02-25T21:40:04Z

‎dragDropCallback

AngelHerraez: /* Model loading */

2025-08-28T09:34:25Z

‎Model loading

AngelHerraez: /* JSmol object definition */

2025-08-28T09:26:51Z

‎JSmol object definition

AngelHerraez: /* Startup period */

2025-08-24T17:29:50Z

‎Startup period

@@ Line 249: / Line 249: @@
 :: for files dropped into JSmol: "DROP_" + filename
 :: for files opened via the dialog raised by <code>load ?</code>: "localLOAD_" + filename
-: arguments[3]: the portion of the filename before .pdb, so if you loaded 2ace.pdb, "2ace".
+: arguments[3]:
 : arguments[4]: null for successful loads.
 : arguments[5]: a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed.

@@ Line 243: / Line 243: @@
 Called: upon file loading (successful or not). In the case of dropping a file into JSmol, this is called after processing the file (later than dragDropCallback is called), but, if a PDB file was dropped, before rendering.
 : arguments[0]: the name of the JSmol object, e.g. jmolApplet0 or presumably jmolAppletN for the Nth of multiple applets if they were not given a particular custom name.
-: arguments[1]: the URL of the loaded file (full path+filename), or for dropped files, "cache://DROP_" + filename.
+: arguments[1]: the URL of the loaded file (full path+filename), or:
-: arguments[2]: the filename of the loaded file (without the path), or for dropped files, "DROP_" + the filename.
+:: for files dropped into JSmol: "cache://DROP_" + filename
 : arguments[3]: the portion of the filename before .pdb, so if you loaded 2ace.pdb, "2ace".
 : arguments[4]: null for successful loads.

@@ Line 170: / Line 170: @@
 In each case, several parameters are returned and passed to the function (its <code>arguments</code> array):
-# the first parameter returned (argument zero) is always the JSmol object name;
+# <code>arguments</code> is an array variable internal to the callback function; since it is JavaScript, the first element has index zero
 # the 2nd and later parameters hold the information; not all are used by all callbacks (see below).
 Note that the array of arguments is zero-based in JavaScript but 1-based in JmolScript.
@@ Line 241: / Line 242: @@
 === loadStructCallback ===
 Called: upon file loading (successful or not). In the case of dropping a file into JSmol, this is called after processing the file (later than dragDropCallback is called), but, if a PDB file was dropped, before rendering.
-<!-- List corrected by EricMartz 2026.02.25 according to behavior of JSmol 16.2.5 which was the same as JSmol 16.3.49. -->
+: arguments[0]: the name of the JSmol object, e.g. jmolApplet0 or presumably jmolAppletN for the Nth of multiple applets if they were not given a particular custom name.
-: arguments[1]: jmolApplet0 (or presumably jmolAppletN for the Nth of multiple applets).
+: arguments[1]: the URL of the loaded file (full path+filename), or for dropped files, "cache://DROP_" + filename.
-: arguments[2]: the URL of the loaded file (full path+filename), or for dropped files, "cache://DROP_" + filename.
+: arguments[2]: the filename of the loaded file (without the path), or for dropped files, "DROP_" + the filename.
-: arguments[3]: the filename of the loaded file (without the path), or for dropped files, "DROP_" + the filename.
+: arguments[3]: the portion of the filename before .pdb, so if you loaded 2ace.pdb, "2ace".
-: arguments[4]: the portion of the filename before .pdb, so if you loaded 2ace.pdb, "2ace".
+: arguments[4]: null for successful loads.
-: arguments[5]: null for successful loads.
+: arguments[5]: a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed.
-: arguments[6]: a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed.
+: arguments[6]: a text string with the frame number prior to loading the current model, in file.model syntax (for example, "3.1" or "1.1 - 3.31" if a whole range of models was framed).
-: arguments[7]: a text string with the frame number prior to loading the current model, in file.model syntax (for example, "3.1" or "1.1 - 3.31" if a whole range of models was framed).
+: arguments[7]: a text string with the last frame number after loading the current model, in file.model syntax.
 *Note 1: When multiple files are loaded with the same load command, only data for the last-loaded file is returned.
-*Note 2: When using the arguments in Javascript with JSmol, you may need to cast them to a number or a string, for example arg3string = "" + arg3; arg6integer = 0 + arg6.
+*Note 2: When using the arguments in JavaScript with JSmol, you may need to cast them to a number or a string, for example arg3string = "" + arguments[3]; arg6integer = 0 + arguments[6].
 === measureCallback ===

@@ Line 242: / Line 242: @@
 Called: upon file loading (successful or not). In the case of dropping a file into JSmol, this is called after processing the file (later than dragDropCallback is called), but, if a PDB file was dropped, before rendering.
 <!-- List corrected by EricMartz 2026.02.25 according to behavior of JSmol 16.2.5 which was the same as JSmol 16.3.49. -->
-: arguments[1]: jmolApplet0
+: arguments[1]: jmolApplet0 (or presumably jmolAppletN for the Nth of multiple applets).
 : arguments[2]: the URL of the loaded file (full path+filename), or for dropped files, "cache://DROP_" + filename.
 : arguments[3]: the filename of the loaded file (without the path), or for dropped files, "DROP_" + the filename.

@@ Line 250: / Line 250: @@
 : arguments[7]: a text string with the frame number prior to loading the current model, in file.model syntax (for example, "3.1" or "1.1 - 3.31" if a whole range of models was framed).
 : arguments[8]: a text string with the last frame number after loading the current model, in file.model syntax.
-Note 1: When multiple files are loaded with the same load command, only data for the last-loaded file is returned.
+*Note 1: When multiple files are loaded with the same load command, only data for the last-loaded file is returned.
-Note 2: When using the arguments in Javascript with JSmol, you may need to cast them to a number or a string, for example arg3string = "" + arg3; arg6integer = 0 + arg6.
+*Note 2: When using the arguments in Javascript with JSmol, you may need to cast them to a number or a string, for example arg3string = "" + arg3; arg6integer = 0 + arg6.
 === measureCallback ===

@@ Line 212: / Line 212: @@
 === dragDropCallback ===
-Called: when a file is dropped into the JSmol panel
+Called immediately when a file is dropped into the JSmol panel, before the file is processed. (loadStructCallback is called after the file is processed, but, in the case of a PDB file, before it is rendered.)
 : arguments[1]: a number ''(this needs explanation)''
 : arguments[2]: x (coordinate within the JSmol panel where the pointer was released at dropping)

@@ Line 97: / Line 97: @@
 : Note that using <code>script</code> will cancel whatever <code>src</code> specifies (but it is easy to include a <code>load</code> command as part of the script)
 * '''defaultModel''' <code>""</code>
-:The name or id of a model to be retrieved from a public database, and displayed when the JSmol object has finished loading.
+:The name or id of a model to be [[Database_Connection|retrieved from a public database]], and displayed when the JSmol object has finished loading.
 :Examples:
 ::<code>defaultModel: "=1crn"</code>  gets it from RCSB PDB
 ::<code>defaultModel: "$caffeine"</code>  gets it from NCI CACTUS
 ::<code>defaultModel: ":caffeine"</code>  gets it from PubChem
 == Customization or extras ==

@@ Line 35: / Line 35: @@
 :The width of the JSmol object in pixels or expressed as percent of its container width as a string in quotes: "100%".
-Note that for a percent to work, '''''all''''' surrounding HTML elements must explicitly implement the CSS attributes <code>style=height:...</code> and <code>style=width:...</code>. That includes setting height to 100% for <code>body</code> and <code>html</code>.
+Note that for a percent to work, the parent container must have explicit <code>style=height:...</code> and <code>style=width:...</code>.
 === Background color ===
 * '''color''' <code>"white"</code>
-:The background color of the JSmol object, as a quoted text string in any JmolScript-supported format: color name, decimal triplet <code>[r,g,b]</code> or hexadecimal <code>[xRRGGBB]</code>, or in html-style format:  <code>#RRGGBB</code>. Note that default is now white, in contrast to black in the legacy Jmol.js method.
+:The background color of the JSmol object, as a quoted text string in any JmolScript-supported format: color name, decimal triplet <code>[r,g,b]</code> or hexadecimal <code>[xRRGGBB]</code>, or in html-style format:  <code>#RRGGBB</code>. Note that the current default is white, in contrast to black in the legacy Jmol.js method.
 === Files and paths ===
 * '''j2sPath''' <code>"j2s"</code>
-:''(HTML5 modality)'' The path to {{folder|j2s}} including its own name; the contents of this folder are essential for JSmol to work.
+:The path to {{folder|j2s}} including its own name; the contents of this folder are essential for JSmol to work.
 * '''serverURL''' <code>"<nowiki>http://your.server.here/jsmol.php</nowiki>"</code>
-:The URL of {{file|jsmol.php}} to be used for getting file data into non-Java modalities. For better performance and to avoid cross-domain issues, '''you should set this''' to a url in the same server your pages are. In the scheme of the standard JSmol distribution, that will be <code>"<nowiki>php/jsmol.php</nowiki>"</code>.
+:The URL of {{file|jsmol.php}} to be used for getting molecular data, at least for some file formats. For better performance and to avoid cross-domain issues, '''you should set this''' to a url in the same server your pages are. In the scheme of the standard JSmol distribution, that will be <code>"<nowiki>php/jsmol.php</nowiki>"</code>.
 :If you cannot have PHP working in your server, you may use <code>"<nowiki>https://chemapps.stolaf.edu/jmol/jsmol/php/jsmol.php</nowiki>"</code>, since that is a public site accessible to cross-domain AJAX calls.
 :'''Setting this properly is essential''', among other situations,
@@ Line 54: / Line 53: @@
 === Modality ===
 * '''use''' <code>"HTML5"</code> This string determines the mode to be used (either Java applet or a surrogates).
-** The default setting is <code>HTML5</code> and indicates to use JSmol in html5-only mode.
+** <code>HTML5</code> is the default setting and indicates to use JSmol in html5-only mode.
-** The value <code>WebGL</code> will force the [[Jmol_JavaScript_Object/WebGL|WebGL modality]] (combined with html5). ''Note that the WebGL version of JSmol does not implement the full set of functionalities of Jmol.''
+** <code>WebGL</code> is an alternative value to force the [[Jmol_JavaScript_Object/WebGL|WebGL modality]] (combined with html5). ''Note that the WebGL version of JSmol does not implement the full set of functionalities of Jmol; see those [[Jmol_JavaScript_Object/WebGL#Support_for_JmolScript_features|limitations]].''
-** The value <code>Java</code> forces use of the Jmol Applet (and it may display a message if Java is not enabled). ''Note that Java applets are no longer supported by the majority of web browsers.''
+** <code>Java</code> is the legacy value (now deprecated) to force use of the [[Jmol_Applet/Legacy|Jmol Applet]] (and it may display a message if Java is not enabled in the browser). ''Note that Java applets are no longer supported by the majority of web browsers.''
 == Startup period ==

@@ Line 81: / Line 81: @@
 :If set <code>true</code>, avoids the display of messages in a single line, colored, at bottom-left of the page while code loads (both initially and every time a new module is requested by a running script).
 * '''readyFunction''' <code>null</code>
-:The name (''without quotes'') of a JavaScript function to call when the JSmol object has been created and is ready to receive commands (and also called when the object is destroyed e.g. when the page is closed).
+:The name (''without quotes'') of a JavaScript function to call when the JSmol object has been created and is ready to receive commands.
 : For example, with <code>readyFunction: jmolIsReady</code> any of the following JavaScript function definitions could be used:
-:: <code>function jmolIsReady() { alert('Welcome to Jmol!'); }</code>
+:: <code>function jmolIsReady() { alert('Welcome to JSmol!'); }</code>
-:: <code>jmolIsReady = function() { alert('Welcome to Jmol!'); }</code>
+:: <code>jmolIsReady = function() { alert('Welcome to JSmol!'); }</code>
 :: <code>jmolIsReady = function(theJmol) { document.title = theJmol._id + " is ready"; }</code>
 == Model loading ==