View source for Jmol JavaScript Object

== Jmol-JSO ==

The Jmol JavaScript Object ('''Jmol-JSO''') is a set of JavaScript functions and utilities refactored and reorganized for Jmol 13.0 into a single JavaScript object (<code>window.Jmol</code>). The library {{file| JSmol.min.js}} supersedes the [{{Website}}jslibrary/ Jmol.js JavaScript library], 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 replaced by a non-Java HTML5 canvas element (which might not even be Jmol) or even an image, depending on client platform's resources. 

'''Jmol-JSO''' was initially developed by Bob Hanson and Paul Pillot in early 2012. It was folded into '''JSmol''' in late 2012. 

Using '''Jmol-JSO''', a web page developer can target Java-challenged (iPad, iPhone) and applet-challenged (Android) platforms using '''a Jmol applet surrogate''' while still implementing Jmol/Java 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...."

'''Jmol-JSO''' also integrates facilities for direct, behind-the-scenes access to public databases such as the [http://rcsb.org RCSB PDB database], the [http://cactus.nci.nih.gov/ National Cancer Institute CACTVS server], and [http://pubchem.ncbi.nlm.nih.gov/ PubChem], even when the user's platform does not allow the Jmol Java applet.

In addition, '''Jmol-JSO''' allows easy interaction with
* the '''JSpecView Java applet''', allowing one to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra (see [[Jmol_JavaScript_Object/JSV|more details]])
* the '''JME Java applet''', so 3D models can be generated by a page visitor using simple chemical 2D drawing (see [[Jmol_JavaScript_Object/JME|more details]])

'''Jmol-JSO''' is fully compatible with [http://jquery.com jQuery] (although it requires its own customization of jQuery, {{file|JSmoljQuery.js}}). The library has been W3C and XHTML validated.

===Main features of Jmol-JSO ===
<table class="wikitable">
<tr>
<th>Non-Java Options</th><td>Options for Java, HTML5/WebGL, HTML5-only, and image-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.</td>
</tr>
<tr>
<th>Library Files</th>
<td>Requires at a minimum, {{file|JSmol.min.js}} and {{folder|j2s}} and/or {{folder|java}}.</td>
</tr>
<tr>
<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>
</tr>
<tr>
<th>JavaScript Prototypes</th>
<td>The object you create using <code>Jmol.getApplet()</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 Java applet/canvas itself. The applet or canvas is wrapped in a set of <code>div</code> elements, allowing a richer diversity of options.</td>
</tr>
<tr>
<th>AJAX</th>
<td>Jmol-JSO includes methods to easily access cross-platform resources using AJAX provided by jQuery.</td>
</tr>
<tr>
<th>REST services</th>
<td>Jmol-JSO lets you access keyword search results from RCSB -- for example, a list of all structures that reference ''caffeine''.</td>
</tr>
<tr>
<th>Scripting</th>
<td>Jmol-JSO in conjunction with JSmol provides the same full complement of scripting that Jmol offers. Jmol-JSO accepts script commands immediately, before or during applet/canvas creation on the page, caching them until Jmol is ready to accept them.</td>
</tr>
</table>

== JSmol ==
<div style="float:left;">
[[Image:JSmol_logo13.png]]
</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''' 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 [http://java2script.sourceforge.net/ 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
** MSIE allows access to non-binary local files only
** Opera allows no access to local files
** Chrome allows access only when using a command-line flag
* 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).
* 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.

=== 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: 
{{file|.bin}}
{{file|.gz}}
{{file|.zip}}
{{file|.jpg}}
{{file|.png}}
{{file|.jmol}}
{{file|.smol}}
{{file|.spartan}}
{{file|.mrc}}
{{file|.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 <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.

=== 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 {{file|Jmol.js}} to {{file|JSmol.min.js}}
* Adding the {{folder|java}} or {{folder|j2s}} folders/directories to your website. 
* Setting parameters in the <code>Info</code> 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 a set of JavaScript functions that allow you to use all the methods on your page that you already use. For example, if you use the simplest from of jmolButton:

<pre>
function jmolButton(script, label) {
  Jmol.jmolButton(myJmol, script, label)
}
</pre>

Or you can just modify your function to the new format. All of the main methods found in {{file|Jmol.js}} (and more!) can be found in {{file|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:

* ''Step 1, method A:''
** In all your pages, add a call to {{file|JSmol.min.js}}
** In all your pages, change the existing call to {{file|Jmol.js}} into {{file|Jmol2.js}}
* ''Step 1, method B:''
** Open in a text editor both {{file|JSmol.min.js}}, {{file|Jmol2.js}} and a new blank document. Combine in this document the contents of {{file|JSmol.min.js}} followed by the contents of {{file|Jmol2.js}}. Save this new document as {{file|Jmol.js}} 
** Keep in your pages the existing call to {{file|Jmol.js}}
* ''Step 2:''
** Add the JSmol files and folders as appropriate (described in the Installation and Initialization sections of this page).

For more details, read inside the Jmol2.js file itself.

Locations to get {{file|Jmol2.js }}:
* In the Jmol download, Jmol-14.x.x-binary.zip > jsmol.zip > jsmol\js\Jmol2.js
* In the [{{SVN JSmol Trunk}}jsmoljs/Jmol2.js JSmol repository]
* [{{StOlaf}}jsmol/js/Jmol2.js at StOlaf]

=== Upgrading Jmol without using JSmol ===

If you have a "legacy" site that uses Jmol.js, and you would prefer to stick with Java and just upgrade your site so that it still works, then all you have to do is the following:

* Download the latest [http://sourceforge.net/projects/jmol/files Jmol ZIP file distribution]. Inside the ZIP file is a second ZIP file, jsmol.zip. Extract that file.
* Open jsmol.zip and extract all the JAR and JNLP files in the jsmol/java directory. 
* Retrieve a new version of Jmol.js from [http://chemapps.stolaf.edu/jmol/Jmol.js 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.

==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 [http://sourceforge.net/tracker/?atid=379133&group_id=23629&func=browse bug report] if you find a problem.'' 

===Getting the Files===
Full releases may be obtained at [{{WebsiteJSmol}} the JSmol Project page]. The most up-to-date version of JSmol can be found as [{{StOlaf}}zip/ St. Olaf]. 

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

* 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.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.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).

* {{folder|php}}
** {{file|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 <code>load</code> command, or when using <code>var x = load(...)</code> 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|.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|java}} The files for the 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.)
* {{folder|js}} The suite of JavaScript libraries needed for building the Jmol-JSO object (but most of these files are already included in packed form within {{file|JSmol.min.js}}, see below):
** {{file|j2sjmol.js}} Required interface to the Jmol and java classes (translated into JavaScript and compressed using the Google Closure Compiler.)
** {{file|JSmol.js}} Primary JSmol library, with private methods for creating and interacting with canvases
** {{file|JSmolApi.js}} All pubic user-intended interface functions
** {{file|JSmolApplet.js}} Required applet prototypes for use with Java or HTML5
** {{file|JSmolControls.js}} Required only if any buttons or links or other input methods will be used
** {{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|JSmolGLmol.js}} Needed only when [[Jmol_JavaScript_Object/GLmol|using the WebGL version of JSmol]]
** {{file|JSmolThree.js}} Needed only when [[Jmol_JavaScript_Object/GLmol|using the WebGL version of JSmol]]
* {{folder|j2s}} The suite of JavaScript libraries needed for the HTML5 version of JSmol
* A few sample pages and files, included for your convenience but not required for functionality:
** {{file|jsmol.htm}}, {{file|simple.htm}}, {{file|test2.htm}}, {{file|test3.htm}} , and {{file|cover.htm}} are demonstration/example pages 
** {{folder|data}} 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}}.)

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 only the Jmol Java applet, 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).
* {{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}}.


=== Specific browser considerations ===

==== Firefox/Windows ====

You will be able to read both binary and text files locally. Navigate to about:config and set <b>security.fileuri.strict_origin_policy false</b>.

==== MSIE/Windows ====

No local '''binary''' file access in JSmol/HTML5 from standard script commands. That is, no direct file reading with any of the following in their names:

  .bin .gz .jmol .jpg .map .mrc .omap .png .pse .smol .spartan .zip

This does not apply to files drag-dropped onto the applet or files loaded using "?", which use the HTML5 FileReader object. That method reads binary files without a problem.

==== Chrome/Windows ====

Start Chrome using the command-line flag '''--allow-file-access-from-files''' for local file access. Beyond that, same as for MSIE/Windows.


==== Opera/Windows ====
TODO

==== Firefox/Mac ====
TODO

==== Chrome/Mac ====
TODO

==== Safari/Mac ====
TODO

==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 [[wikipedia:Byte_order_mark#UTF-8|BOM]], but this needs further confirmation).

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 <code>head</code> section (pointing to appropriate paths if not the same folder as the web page as shown here):

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

: 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'''
:: <code>http:</code> {{file|.jar}} files must be located in the same folder as data files or in a folder above this.
:: <code>file:</code> same
: '''signed applet''' 
:: <code>http:</code> no restrictions
:: <code>file:</code> same as unsigned applet
: '''HTML5 JSmol'''
:: <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.
: ''All this needs confirmation''. See also [[Troubleshooting/Applet#Java_security_errors|Java security policy]] which applies to the Java applet. 

==== 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:

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

and then you use the [[#Jmol.getTMApplet|<code>getTMApplet()</code>]] method.

To partially compensate for the lack of scripting, some [[Jmol_JavaScript_Object/Info#Lightweight_version|specific parameters]] of the Info variable are available.

==== Optional components ====
* [[Jmol_JavaScript_Object/JME|Integration with JME]], a Java-based editor to draw 2D chemical structures (Peter Ertl's Java Molecular Editor)
* [[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/ChemDoodle|ChemDoodle option]] to render the 3D model using ChemDoodle (does not use Java)

=== Setting parameters ===

All of the initialization parameters supported in Jmol.js can be implemented in Jmol-JSO. 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", 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>. To the contrary, <tt>Jmol</tt> (right at the beginning) must be written as such, since it is the internal name and identification of the unique Jmol-JSO constructor.

<code>Info</code> is an associative array (a set of key+value pairs) indicating all the desired characteristics of the Jmol object. The principal keys and their default values are given below:
<pre>
var Info = {
  color: "#FFFFFF",  // white background (note this changes legacy default which was black)
  height: 300,      // pixels (but it may be in percent)
  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
  memoryLimit: 512,             // only used in the Java modality
  serverURL: "php/jsmol.php", // needed only for some features, but should 
                              // be in your server for full functionality
  defaultModel: "",
  script: null,
  src: null,
  readyFunction: null,
  addSelectionOptions: false,
  debug: false
};	 
</pre>

[[Jmol_JavaScript_Object/Info|Detailed explanation]] of the parameters of the <code>Info</code> variable.

==== 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 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' (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. <code>?parameter1=value1&parameter2=value2&...etc.</code>

Examples (you get the meaning, don't you?):
<pre>
any.htm?_USE=HTML5
any.htm?_USE=JAVA
any.htm?_USE=SIGNED
any.htm?_JAR=http://some.url.com/some/jsmol/java
any.htm?_J2S=http://some.url.com/some/jsmol/j2s
any.htm?_USE=JAVA&_JAR=http://some.url.com/some/jsmol/java
any.htm?_USE=HTML5&_J2S=http://some.url.com/some/jsmol/j2s
</pre>

Note that the names, like <code>_USE</code>, must be uppercase. The values are case-insensitive.

== Functions for creation or display of Jmol Objects ==

The following functions all relate to applet creation or display. All of them must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.

=== getApplet === 
Definition: <code>Jmol.getApplet = function(id, Info, checkOnly)</code>

This function creates in JavaScript space of the webpage the Jmol object (either a Jmol/Java applet or a JSmol object). For example:
 Jmol.getApplet("myJmol", Info);

The above example will create a <tt>myJmol</tt> variable that holds the Jmol Object, and the object will be inserted in the page (unless <code>Jmol.setDocument()</code> has been set false, see below).

<tt>checkOnly</tt> is an optional true/false flag that allows, when set <code>true</code>, to get a JavaScript Object that can be checked to see what type of Jmol Object ''would'' be created on this particular platform -- a signed Java applet, an unsigned Java applet, a JSmol canvas, an image, a WebGL canvas, etc.

=== getTMApplet === 

This function creates and inserts the [[#Lightweight_JSmol|lightweight variety]] of JSmol object. For example:
 Jmol.getTMApplet("myJmol", Info);

:Note: the reason for the name is that this lightweight alternative was inspired on a viewer named TwirlyMol.

=== getAppletHtml === 

Definition:  <code>Jmol.getAppletHtml = function(JmolObject)</code>

or: <code>Jmol.getAppletHtml = function(id, Info)</code>

Useful for inserting the Jmol object code into the page, either after page has loaded or in the case when the object was generated and stored in a variable, e.g. after <code>Jmol.setDocument(0)</code>. It is particularly useful with <code>.innerHTML</code> inside <code>window.onload</code> or in a function fired by user action  (or the jQuery equivalents <code>.html</code> and <code>$(document).ready</code>). Some examples:
<pre>
window.onload = function(){
  Jmol.setDocument(0);
  Jmol.getApplet("jmol1", Info); // creates the object but does not insert it
  Jmol.getApplet("jmol2", Info);
  [...] // other actions, that may affect the Jmol objects
  // now, let's insert the objects in the page:
  document.getElementById("place1").innerHTML = Jmol.getAppletHtml(jmol1);
  document.getElementById("place2").innerHTML = Jmol.getAppletHtml(jmol2);
});
</pre>
jQuery equivalent syntax:
<pre>
$(document).ready(function(){
  Jmol.setDocument(0);
  Jmol.getApplet("jmol1", Info); // creates the object but does not insert it
  Jmol.getApplet("jmol2", Info);
  [...] // other actions, that may affect the Jmol objects
  // now, let's insert the objects in the page:
  $("#place1").html(Jmol.getAppletHtml(jmol1));
  $("#place2").html(Jmol.getAppletHtml(jmol2));
});
</pre>
Or a simpler syntax that creates the object and inserts it at the same time:
<pre>
window.onload = function(){
  document.getElementById("place1").innerHTML = Jmol.getAppletHtml("jmol1", Info);
  document.getElementById("place2").innerHTML = Jmol.getAppletHtml("jmol2", Info);
});
</pre>

See also under [[Jmol_JavaScript_Object#Jmol.setDocument|Jmol.setDocument()]]

=== getVersion === 

Definition: <code>Jmol.getVersion = function()</code>

This function returns the version of Jmol-JSO, like <code>Jmol-JSO 13.1.12</code>.

Example:
<pre>
var t = Jmol.getVersion(myJmol);
alert(t);
</pre>

=== resizeApplet === 

Definition: <code>Jmol.resizeApplet = function(JmolObject,size)</code>

(Untested in the HTML5 version of JSmol.) Used to change the dimensions of the specified Jmol object.
					
<tt>size</tt>: a value or a pair of width/height values in an array, either expressed in pixels or as percent.

Examples:
<pre>
Jmol.resizeApplet(myJmol, 400);
Jmol.resizeApplet(myJmol, [400,700]);
Jmol.resizeApplet(myJmol, "100%");
Jmol.resizeApplet(myJmol, ["50%","60%"]);
</pre>

=== setAppletSync === 

Definition: <code>Jmol.setAppletSync = function(JmolObjects, commands, isJmolJSV)</code>

=== setDocument === 

Definition: <code>Jmol.setDocument = function(doc)</code>

<tt>doc</tt> is the target html context where the Jmol Object must be created.

If using <code>Jmol.setDocument(false)</code> or <code>Jmol.setDocument(0)</code>, 
the Jmol Object may be later inserted using <code>Jmol.getAppletHtml()</code>.
What happens is that the HTML code for the object is
put into the internal <code>applet._code</code> variable and not written to the page.
Then you can still refer to the applet, but place it on the page after the controls are made,
or inject ot into the page upon some user action. 

Example:
<pre>
Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
document.getElementById('someContainer').innerHTML = Jmol.getAppletHtml(myJmol);
</pre>
or, using jQuery syntax;
<pre>
Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
$("#someContainer").html(Jmol.getAppletHtml(myJmol));
</pre>

For some situations this may be equivalent to a simpler alternative: 
Just define the Jmol object variable like <code>var myJmol = "myJmol"</code> and then, 
"myJmol" will suffice when providing any options or creating buttons and controls.
Finally, use <code>Jmol.getApplet(myJmol,....)</code> and the Object will work.

=== setGrabberOptions === 
Definition: <code>Jmol.setGrabberOptions = function(options)</code>

Allows to customize the items offered in the drop-down menu that fetches molecules from databases, when using <code>addSelectionOptions:true</code>. Example:
 Jmol.setGrabberOptions([
   ["$", "small molecules at NCI"],
   [":", "small molecules at PubChem"],
   ["==", "ligands at PDB"],
   ["=", "macromolecules at PDB"]
 ])

The first value in each element is the JmolScript prefix to direct the request to the database (this cannot be customized). The second value is the text that is displayed in the drop-down menu in the page, below the Jmol object.

=== showInfo === 

Definition: <code>Jmol.showInfo = function(JmolObject, tf)</code>

This displays or hides the information panel (which holds the log console, or maybe an associated JME applet). By default, that panel is located in the same position as the Jmol viewer, so displaying Info will hide Jmol and vice versa.

The <tt>tf</tt> parameter is a true or false flag.

=== setInfo === 	

Definition: <code>Jmol.setInfo = function(JmolObject, info, isShown)</code>

Sets the information div for the Jmol object to be ''info'' (HTML) and optionally displays it.

=== setXHTML ===

Definition: <code>Jmol.setXHTML = function(id)</code>

Indicates id of the DOM node into which the Jmol object will be inserted, following XHTML format when creating page elements. Largely untested.

Example:
<pre>
<!doctype html>
<head>
<meta charset="UTF-8" />
<title>test XHTML</title>
<script type="text/javascript" src="JSmol.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
  var Info = {
    height: 300,
    width: 300,
    j2sPath: "j2s",
    use: "HTML5"
  };
  Jmol.setXHTML('myContainer');
  Jmol.getApplet(myJmol, Info);
});
</script>
</head>
<body>
<p>Some text</p>
<div id="myContainer"></div>
<p>Some more text</p>
</body>
</html>
</pre>

== Functions for creating controls ==

These Jmol functions create elements of the page that the page visitor can use to interact with the
applet or applet surrogate. Again, all these functions must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.

The first parameter for nearly all of these functions, <tt>JmolObject</tt>, must be a reference to the object that will receive action of the control. Such reference is either the JSO object itself or its name-id (e.g. "myJmol" in the examples above).

:In the following descriptions, a <em style="color:peru;">colored italic font</em> is used for parameters that are optional.  

=== jmolButton === 

Inserts in the page a button with a text content.

Definition: <code>Jmol.jmolButton(JmolObject, script<em style="color:peru;">, label, id, title</em>)</code>

Example:
 var myInfo = {
   color: "#DDDDFF",
   script: "load myMolecule.mol;",
   height: 300,
   width: 300
 };
 Jmol.getApplet("myJmol", myInfo);
 Jmol.jmolButton(myJmol,"spacefill on", "display as vdW spheres");

<tt>script</tt> is run when the button is pressed.
As a special syntax (valid for any other controls as well as the button described here), instead of a Jmol script you can run a JavaScript function that you have defined, by providing this in place of the script: <code>[funcName, param1, param2, param3...]</code>
The function must be defined in this way:
 function funcName(btn, obj, target) {
     // Entire array object is provided as 2nd argument.
     var param1 = obj[1];
     var param2 = obj[2];
     var param3 = obj[3];
     // JavaScript to execute here.
     ....
 }

<tt>label</tt> is the text in the button; if not specified, it defaults to the first 32 characters of the script.

<tt>id</tt> (optional) will be set as both the HTML id and HTML name. It will default to jmolButton0, jmolButton1, etc.

:''Advanced:''
:In addition, the button will be included in a <code><nowiki><span></nowiki></code> element that will have an HTML id of "span_" plus the given <tt>id</tt>, and an HTML title of the given <code>title</code>.
:Browsers will hence show <tt>title</tt> as a tooltip when mouse pointer stays over the button. 

=== jmolCheckbox === 
Definition: <code>Jmol.jmolCheckbox(JmolObject, scriptWhenChecked, scriptWhenUnchecked, labelHtml<em style="color:peru;">, isChecked, id, title</em>)</code>

Inserts a checkbox into the page, followed immediately by <tt>labelHtml</tt>. 

<tt>scriptWhenChecked</tt> is run when the checkbox is checked by the user.

<tt>scriptWhenUnchecked</tt> is run when the user unchecks the checkbox. 

<tt>isChecked</tt> should be set to a non-false value (e.g.: <tt>true</tt>) if you want the checkbox to be checked or marked upon page loading (default: unchecked). 

<tt>id</tt> will be set as both the HTML id and HTML name. It will default to jmolCheckbox0, jmolCheckbox1, etc. 

Browsers will show <tt>title</tt> as a tooltip when mouse pointer stays over the checkbox or over its accompanying <tt>labelHtml</tt>. 

Example:
 Jmol.jmolCheckbox(myJmol,"spacefill on","spacefill off","toggle display as spheres");

=== setCheckboxGroup ===
Definition: <code>Jmol.setCheckboxGroup(chkMaster,chkBoxes)</code>

Starting with previously inserted checkboxes (using <code>Jmol.jmolCheckbox()</code>), this allows to establish a relation between one "parent" or "leader" checkbox and one or more "child" or "follower" checkboxes, according to these rules: 
* Whenever the leader is checked, all its followers get automatically checked.
* Whenever the leader is unchecked, all its followers get automatically unchecked.
* Whenever one of the followers is checked or unchecked, its siblings are examined; if all have the same state, the leader will be checked or unchecked accordingly.

The Jmol scripts associated to each checkbox when it was inserted/defined will be executed when its state changes due to action on another checkbox.

<tt>chkMaster</tt>  is the ID given to the checkbox that will act as leader. This ID may have been specified in its <code>Jmol.jmolCheckbox()</code>) definition, or may be a number (if ID was not specified, sequential numeric IDs are assigned by default, starting from zero). 

<tt>chkBoxes</tt> is an array of one or more IDs or numbers, pointing to the checkboxes that will act as followers. 

Any number of groups can be set in a page, with any number of component checkboxes. Nesting groups within other groups is also possible (i.e., a follower in one group may be the leader for an inner group). 

=== jmolCommandInput === 
Definition: <code>Jmol.jmolCommandInput(JmolObject<em style="color:peru;">, label, size, id, title</em>)</code>

=== jmolLink === 
Definition: <code>Jmol.jmolLink(JmolObject, script<em style="color:peru;">, text, id, title</em>)</code>

<tt>script</tt> is run when the user clicks on the link.

<tt>text</tt> is written to the page as a link. If it is not specified, it defaults to the first 32 characters of <tt>script</tt>.

<tt>id</tt> will be set as both the HTML id and HTML name. It will default to jmolLink0, jmolLink1, etc.

Example:
 Jmol.jmolLink(myJmol,"load adenine.mol","adenine");

:''Advanced:''
:In addition, the link text will be included in a <code><nowiki><span></nowiki></code> element that will have an HTML id of "span_" plus the given <tt>id</tt>, and an HTML title of the given <tt>title</tt>.
:Browsers will hence show <tt>title</tt> as a tooltip when mouse pointer stays over the link. 

=== jmolMenu === 
Definition: <code>Jmol.jmolMenu(JmolObject, arrayOfMenuItems<em style="color:peru;">, size, id, title</em>)</code>

=== jmolRadio === 
Definition: <code>Jmol.jmolRadio(JmolObject, script<em style="color:peru;">, labelHtml, isChecked, separatorHtml, groupName, id, title</em>)</code>

Inserts a single radio button into the page, followed immediately by <tt>labelHtml</tt>.  

<tt>script</tt> is run when the user checks the radio button.

<tt>labelHtml</tt> is written to the page right after the radio button. Note that it '''must''' be a text string (if you wanted to use a number, wrap it in quotes). 

<tt>isChecked</tt> should be set to a non-false value (e.g.: <tt>true</tt>) if you want the radio button to be  marked upon page loading (default: not checked). 

Radio buttons will be assigned to the group specified by <tt>groupName</tt>. In other words, linked radio buttons (those mutually exclusive in their checked state) will be those that share the same value of <tt>groupName</tt>. If you don't want to use a groupName, all buttons will be assigned to the same group (with an automatically assigned name).

<tt>separatorHtml</tt> is used to specify HTML code that should be placed after the radio button and its <tt>labelHtml</tt>. For example, to put the radio buttons on separate lines you should pass in <tt><nowiki><br></nowiki></tt> as the actual parameter. If <tt>separatorHtml</tt> is not specified, it defaults to a non-breaking space. 

<tt>id</tt> will be set as the HTML id. If not provided, a default name is made up automatically.

The radio button label will be surrounded by <tt><nowiki><label></nowiki></tt> tags; the effect is that clicking on the label text will have the same effect as clicking on the radio button itself. 

Example:
 Jmol.jmolRadio(myJmol,"spacefill 23%; wireframe 0.15;","ball and stick",true);

=== jmolRadioGroup === 
Definition: <code>Jmol.jmolRadioGroup(JmolObject, arrayOfRadioButtons<em style="color:peru;">, separatorHtml, groupName, id, title</em>)</code>

Inserts a group of mutually-exclusive radio buttons into the page.  

<tt>arrayOfRadioButtons</tt> is usually specified using the JavaScript square brackets [ entryA, entryB, ... ] notation. Each entry is generally another array which contains a script, a label (text displayed in the page after the radio button), and an optional isChecked flag. If an entry is a single string instead of an array, then that string is used for both the script and the label. 

<tt>separatorHtml</tt> is used to specify HTML code that should be placed after each radio button and its label, but before the next radio button. For example, to put the radio buttons on separate lines you should pass in <tt><nowiki><br></nowiki></tt> as the actual parameter. If <tt>separatorHtml</tt> is not specified, it defaults to a non-breaking space. 

Radio buttons will all belong to a group with an HTML name of <tt>groupName</tt>. If you don't specify one, it will be automatically made up.

The whole group of radio buttons will be included in a <tt><nowiki><span></nowiki></tt> element that will have as its HTML id the value of <tt>id</tt> or, if this is not given, the value of <tt>groupName</tt>.
In turn, each radio button + label will have as its HTML id <tt>span_</tt> plus the group's <tt>id</tt> plus an underscore plus a sequential number (starting at zero), and as its HTML title, the common <tt>title</tt>.
Each radio button label will be surrounded by <tt><nowiki><label></nowiki></tt> tags; the effect is that clicking on the label text will have the same effect as clicking on the radio button itself. 

Example:
<pre> var r = [
    ["spacefill 23%; wireframe 0.15;","ball and stick",true],
    ["spacefill off; wireframe 0.15;","sticks"],
    ["spacefill on; wireframe off;","spheres"]
 ];
 Jmol.jmolRadioGroup(myJmol, r, "<br>", "atomstyle");
</pre>

== Functions that insert HTML ==

These simple commands just deliver HTML to the page. They are merely convenience functions for use 
from within the <code>body</code> so as not to have to continually switch in and out of script tags. 

Again, all these functions must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.

:Much better practice is to do all control creation in the header of the page, from within jQuery's <code>$(document).ready()</code> function, using <code>Jmol.setDocument(0)</code>, appending the HTML to a growing string using the control-specific functions, then setting the code in a predefined <code>div</code> element using the jQuery <code>$('#divId').html()</code> function.

=== jmolBr === 
Inserts a soft line break. Its only use is:
 Jmol.jmolBr()

=== jmolHtml === 
Allows to insert in the page any HTML code you may wish. Example:
 <nowiki>Jmol.jmolHtml(' <b style="color:red">H<sub>2</sub>O</b> ')</nowiki>

== Functions that set CSS rules ==

These functions, called prior to the creation of the associated object(s), allow the page designer
to add specific attributes (usually, but not necessarily CSS style attributes) to the HTML tag(s) that
will be created later. This allows setting one or more common style attributes for, for example, all 
buttons in a certain cell of a table, or all radio buttons of a certain group. Either a class name or an attribute can be given. For example:
<pre>
  Jmol.setButtonCss(null, "style='width:160px'");
</pre>

Again, all these functions must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.

=== setAppletCss === 
Definition: <code>Jmol.setAppletCss = function(cssClass, text)</code>

=== setButtonCss === 
Definition: <code>Jmol.setButtonCss = function(cssClass, text) </code>

=== setCheckboxCss === 
Definition: <code>Jmol.setCheckboxCss = function(cssClass, text) </code>

=== setLinkCss === 
Definition: <code>Jmol.setLinkCss = function(cssClass, text) </code>

=== setMenuCss === 
Definition: <code>Jmol.setMenuCss = function(cssClass, text)</code>

=== setRadioCss ===
Definition: <code>Jmol.setRadioCss = function(cssClass, text)</code>


== Other public methods ==

All these functions must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.

===  script ===
Definition: <code>Jmol.script(JmolObject, myScript)</code>

<tt>myScript</tt> (a text string containing one or several Jmol commands) is run immediately.

Examples:
 Jmol.script(myJmol,"spacefill off; wireframe 0.3;");
 Jmol.script(myJmol,"script someScript.spt;");

===  scriptWait ===
Definition: <code>Jmol.scriptWait(JmolObject, myScript)</code>

Same as <tt>Jmol.script()</tt> except that any further Jmol scripts will not be run until execution of <tt>myScript</tt> has finished.


=== Other ===

(''TO-DO -- just transfer text with slight modification from [{{Website}}jslibrary/ jslibrary]'')

Definitions:
 Jmol.evaluate = function(applet,molecularMath) 
 Jmol.getInfo = function(applet) 
 Jmol.getPropertyAsArray = function(applet,sKey,sValue)
 Jmol.getPropertyAsJavaObject = function(applet,sKey,sValue)
 Jmol.getPropertyAsJSON = function(applet,sKey,sValue) 
 Jmol.getPropertyAsString = function(applet,sKey,sValue)
 Jmol.getStatus = function(applet,strStatus) 
 Jmol.loadFile = function(applet, fileName, params)
 Jmol.restoreOrientation = function(applet,id) 
 Jmol.restoreOrientationDelayed = function(applet,id,delay)
 Jmol.saveOrientation = function(applet,id) 
 Jmol.say = function(msg) 
 Jmol.scriptEcho = function(applet, script) 
 Jmol.scriptMessage = function(applet, script) 
 Jmol.scriptWaitAsArray = function(applet, script) 
 Jmol.scriptWaitOutput = function(applet, script)  
 Jmol.search = function(applet, query, script)

Examples:
 var s = Jmol.getPropertyAsString(myJmol,'stateInfo');
 im.src = 'data:image/jpeg;base64,' + Jmol.getPropertyAsString(JmolObject,'image');

== Methods specific to optional components ==
* [[Jmol_JavaScript_Object/JME|Methods specific to the JME applet]]
* [[Jmol_JavaScript_Object/JSV|Methods specific to the JSpecView applet]]