Difference between revisions of "Jmol JavaScript Object/Info"
AngelHerraez (talk | contribs) (current defaults for Info) |
AngelHerraez (talk | contribs) (→Model loading) |
||
Line 92: | Line 92: | ||
:A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed. | :A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed. | ||
* '''defaultModel''' <code>""</code> | * '''defaultModel''' <code>""</code> | ||
− | :The name of a model to be retrieved from a public database, and displayed when the Jmol object has finished loading. | + | :The name or id of a model to be retrieved from a public database, and displayed when the Jmol object has finished loading. |
:Examples: | :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 NCI CACTUS | ||
::<code>defaultModel: ":caffeine"</code> gets it from PubChem | ::<code>defaultModel: ":caffeine"</code> gets it from PubChem |
Revision as of 23:05, 15 September 2014
Documentation of parameters of the Info variable
This page explains the parameters of the Info
variable, an essential part of the Jmol JavaScript Object and hence of JSmol.
Note that, although this is usually designated as Info
in the documentation, it is a regular JavaScript variable that you can name as you wish.
Info is an associative array (a set of key/value pairs) indicating all the desired characteristics of the Jmol object (Jmol applet or JSmol).
Values may be defined
- either during initialization of the
Info
variable:
var Info = { color: "#E8F4FF", height: 400, width: 400 };
- or separately:
Info.color = "#E8F4FF";
Contents
Jmol object definition
(The values shown in the listing below are the defaults)
Dimensions
- height
300
- The size of the Jmol object in pixels or expressed as percent of its container height as a string in quotes: "100%".
- width
300
- The width of the Jmol 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 style=height:...
and style=width:...
. That includes setting height to 100% for body
and html
.
Note also that, despite that, non-Java JSmol uses the canvas
element, which will not resize correctly.
Background color
- color
"white"
- The background color of the Jmol object, as a quoted text string in any JmolScript-supported format: color name, decimal triplet
[r,g,b]
or hexadecimal[xRRGGBB]
, or in html-style format:#RRGGBB
. Note that default is now white, in contrast to black in the classic Jmol.js method.
Files and paths
- jarFile
"JmolApplet0.jar"
- (Java modality only) The file to be used, usually either
JmolApplet0.jar
(for faster incremental loading) orJmolApplet.jar
(a single 2.5+ MB download), or the signed versionsJmolAppletSigned0.jar
andJmolAppletSigned.jar
. Be careful that the setting here should match that of isSigned.
- isSigned
false
- (Java modality only) Make sure to change this to
true
if the file indicated for jarFile is the signed applet.
- jarPath
"java"
- (Java modality only) The path to the applet files. Note that if the unsigned applet is used and the page is tested locally, then all model files must be in or under the folder indicated by this value, to satisfy Java security policy.
- j2sPath
"j2s"
- (HTML5 modality) The path to j2s including its own name; the contents of this folder are essential for JSmol to work.
- serverURL
"http://your.server.here/jsmol.php"
- The URL of 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 your same server. In the scheme of the standard JSmol distribution, that will be
"php/jsmol.php"
. If you cannot have PHP working in your server, you may use"http://chemapps.stolaf.edu/jmol/jsmol/php/jsmol.php"
, since that is a public site accessible to cross-domain AJAX calls. Setting this properly is essential, among other situations, for loading binary files into JSmol in some browsers.
Modality
- use
"HTML5 noJava WebGL noImage"
This string determines the various options to be tried (applet and surrogates) and the order in which to try them.- The default setting is the same as just
HTML5
by itself and indicates to use JSmol in html5-only mode. - The value
Java
forces use of the Jmol Applet (and it may display a message if Java is not enabled). - The value
Java HTML5
would test for Java and then, if that is not available, use JSmol. - A value of
Java Image
would allow PNGJ files to be displayed as images or simple file loading to be delivered as an image from a server if Java is not available. - The value
Java HTML5 WebGL Image
would try sequentially those modalities.
- The default setting is the same as just
Note that Jmol-JSO cannot detect if the user has intentionally disabled Java in some browsers. Thus, users intentionally disabling Java may only get the Java modality, and a message will be displayed that Java is not available.
Startup period
(The values shown in the listing below are the defaults)
- coverImage
""
- Set the path and filename of an image that will be displayed on top of the Jmol object (usually as an initial replacemente or during loading, see
deferApplet
anddeferUncover
parameters below).
- coverTitle
""
- Set a tip that is displayed before model starts to load.
- coverCommand
""
- Set a Jmol command or script that will be executed upon clicking the cover image.
- deferApplet
false
- If set
true
, the model will not be loaded until the user clicks on the cover image (seecoverImage
parameter above).
- deferUncover
false
- If set
true
, the cover image will remain until command execution is complete.
- disableInitialConsole
false
- If set
true
, avoids the display of messages ('console') in the Jmol panel while the Jmol object is being built initially.
- disableJ2SLoadMonitor
false
- If set
true
, 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
null
- The name (without quotes) of a JavaScript function to call when the Jmol 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).
- For example, with
readyFunction: jmolIsReady
any of the following JavaScript function definitions could be used:jmolIsReady = function(theJmol) { document.title = theJmol._id + " is ready"; }
jmolIsReady = function() { alert('Welcome to Jmol!'); }
function jmolIsReady() { alert('Welcome to Jmol!'); }
Model loading
(The values shown in the listing below are the defaults)
- src
""
- A filename to load once the Jmol object has finished loading. It may be a model in a supported format, or a script file.
- script
""
- A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed.
- defaultModel
""
- The name or id of a model to be retrieved from a public database, and displayed when the Jmol object has finished loading.
- Examples:
defaultModel: "=1crn"
gets it from RCSB PDBdefaultModel: "$caffeine"
gets it from NCI CACTUSdefaultModel: ":caffeine"
gets it from PubChemdefaultModel: "caffeine"
gets it from NCI CACTUS
Customization or extras
(The values shown in the listing below are the defaults)
- addSelectionOptions
false
- Set this value to
true
if you want to display, below the Jmol object, a menu with options for loading structures from public databases.
- console
"***_infodiv"
- The ID in html of the container or div that will receive output from Jmol. Default value is the Jmol Object name/id followed by "_infodiv", and it is contained in the info panel that may be displayed alternatively to the Jmol viewer.
- debug
false
- Set this value to
true
if you are having problems getting your page to show the Jmol object, buttons or ther controls.
- language "2-letter or 2+2-letter code"
- This setting can be used to specify a language to be used in the Jmol Object interface (mainly the pop-up menu). The existing choices may be checked in the pop-up menu. If not specified, the default language is automatically detected from the system settings of the user's browser.
- Examples:
language: "es"
for Spanishlanguage: "pt_BR"
for Brazilian Portuguese
- memoryLimit
512
- (Java modality only) The maximum amount of memory allowed for the Java applet, in MB.
- menuFile "fileName"
- Loads a custom pop-up menu.
- usecommandthread
false
- The signed Jmol Java applet generally runs commands by passing them to a command thread that is established when the applet is created, while the unsigned applet does not. You can change this behavior if you are observing Java security issues. Otherwise, it should not be adjusted.
- zIndexBase
9000
- Defines the z-index property in CSS of the Jmol Object and its associated div's. This is set by default to a very high value, so the object will be laid on top of any other page elements, but it may be useful to change it when you are integrating Jmol with other components. In addition to setting for the particular applet, it also sets the default for all other applets on the page, in case it is not defined for those applets.
- z
{9000, 9001, 9002, 9003, 9004, 9005, 9006, 9007, 99008, 100008, 109007}
- Defines, in a more fine-grained way, the z-index property in CSS of all div's forming the Jmol Object.
- It is an associative array that includes (some of these are more relevant to JmolSpecViewer):
Info.z = { header: , rear: , main: , image: , front: , fileOpener: , coverImage: , dialog: , menu: , console: , monitorZIndex: }
- When just
zIndexBase
is provided, it will set all components ofz
in this way:
header: zIndexBase, rear: zIndexBase + 1, main: zIndexBase + 2, image: zIndexBase + 3, front: zIndexBase + 4, fileOpener: zIndexBase + 5, coverImage: zIndexBase + 6, dialog: zIndexBase + 7, menu: zIndexBase + 90000, console: zIndexBase + 91000, monitorZIndex: zIndexBase + 99999
Lightweight version
A special alternative version of JSmol may be invoked, with a very small file size and high responsiveness, particularly adequate for a quick startup and for systems with limited resources and power, like phones.
This version uses a specific js file; since it does not allow scripting, it admits special parameters in the Info
variable:
- shadeAtoms
false
- If set
true
, will apply a shading to atoms to give some 3D appearance. This is experimental and may slow down rendering considerably, so use it consciously.
- bondWidth
5
- multipleBondSpacing
4
- zoomScaling
1.5
- pinchScaling
2
- mouseDragFactor
0.5
- touchDragFactor
0.15
- spin
false
- Default spinning of the model.
- spinRateX
0
- spinRateY
0.5
- spinFPS
20
use:"HTML5"
will be implicitly imposed and you may optionally include addSelectionOptions:true
Callbacks
These callbacks, given in the Info variable, allow the page designer to get information about what is happening within the Jmol object. The name of a JavaScript function, wrapped in single- or double-quotes should be given as value. Do not use function() {....}
syntax.
- (In the former method, Jmol.js, these could be set using either
jmolSetParameter()
orjmolSetCallback()
functions.)
Example:
Info.pickcallback = "myPick"; function myPick(a,b,c,d) { alert('you clicked on atom with index=' + c); }
In each case, several parameters are returned and passed to the function:
- the first parameter returned is the Jmol Object name, followd by "_object");
- the second parameter holds the information;
- additional parameters are returned only in the case of some of the callbacks (see below), and hold additional information.
- animframecallback
- appletreadycallback
- atommovedcallback
- echocallback
- evalcallback
- hovercallback
- loadstructcallback
- Called: upon file loading (successful or not).
- Returned 2nd parameter: the URL of the loaded file (full path+filename).
- Returned 3rd parameter: the filename of the loaded file (without the path).
- Returned 4th parameter: the internal title of the model in the loaded file.
- Returned 5th parameter: any error messages generated.
- Returned 6th parameter: a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed.
- Returned 7th parameter: 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).
- Returned 8th parameter: a text string with the last frame number after loading the current model, in file.model syntax.
- Note: When multiple files are loaded with the same load command, only data for the last-loaded file is returned
- measurecallback
- messagecallback
- minimizationcallback
- pickcallback
- Called: when the user clicks an atom -- or a bond (see below).
- Note that for this to work,
set atomPicking
must be set true (it is by default) - Returned 2nd parameter: atom id, atom number, and xyz coordinates in the form:
C6 #6 -0.30683374 -1.6836332 -0.716934
- Returned 3rd parameter: atom index, starting with 0.
- Returned 4th parameter: null.
- If
set bondPicking true
has been issued, bonds will become clickable and also invoke the callback function, but the return from the function will be different: - Returned 2nd parameter: a text string in the form:
["bond","3 1 C2 #2 -- C4 #4 1.3608072",-0.0,0.9061,-0.30629998]
- meaning ?, ?, atom id, atom number, atom id, atom number, bond length (distance), ?, ?, ?.
- Returned 3rd parameter: ?.
- Returned 4th parameter: a text string in the form:
{model=1.1, index=2, type=bond, info=3 1 C2 #2 -- C4 #4 1.3608072, pt={-0.0, 0.9061, -0.30629998}, modelIndex=0}
- resizecallback
- scriptcallback
- synccallback
Misc.
- boxbgcolor
- boxfgcolor
- boxmessage
- progressbar
- progresscolor
- These five values generally should not be adjusted.