View source for Jmol Applet

{{Running_Jmol_Sections}}
== Jmol Applet ==

[[wikipedia:Java_applet|Java applet]] version of Jmol which allows Jmol to be embedded in web pages (given that viewers have a Java plugin installed). Like with the application, [[Scripting]] is available. For some demonstration pages see http://www.jmol.org/demo/. To see the HTML source use your web browser {{MenuItem|View}} &rarr; {{MenuItem|Page Source}}.

== Installing Jmol Applet ==
{{Installing_Jmol_Sections}}
Download the Jmol package (either <code>.zip</code> or <code>tar.gz</code> format) and extract/uncompress '''only the necessary files''' to the folder of your choice.

Which are those necessary files? For basic use, these:
* {{File|Jmol.js}}, this contains a set of scripting commands that are helpful for interacting with Jmol via a web page (functions for buttons, checkboxes, etc. to interact with the applet). For an overview of functions see the [http://jmol.sourceforge.net/jslibrary/ online documentation] or, for the most up-to-date info, just browse the Jmol.js sourcefile.
* All files whose name starts with {{File|JmolApplet0}} and ends in {{File|.jar}}
* If you will distribute your web page files, you should also include the copyright, license and information files: {{File|COPYRIGHT.txt}}, {{File|LICENSE.txt}} and {{File|README.txt}}

To use JmolApplet within local web pages, e.g. on the hard disk or on CD, see [[Jmol Applet Deployment Local]] for some precautions needed.

For some specific needs, you must use other files; read the sections below about the signed applet.

If the applet does not load, see also [[Solving Java Problems]].


=== Giving JmolApplet more memory to work with ===
Memory available to Jmol is determined by Java. You can check the current memory allocation by opening the pop-up menu in the applet, and the last submenu "About Jmol".

Less or more memory can be allocated by using this parameter:
 -Xmx###M
where the ### must be substituted by a number in megabytes (hence the "M" after it). However, the amount of memory that can be allocated is limited by your existing RAM. For example, on a system with 512 MB RAM, a maximum of 256 MB is allowed for Java.

Examples:
* -Xmx512M   will give 512 Mb maximum memory available.
* -Xmx1024M    will give 1024 Mb maximum memory available.

The place to set this parameter is:

:'''Windows''':

::Control Panel > Java icon (opens the [[Solving_Java_Problems#Java_Control_Panel|Java Control Panel]]) > "Java" tab > "Applet run-time configuration" > "Show" button > on row "JRE" (latest version if there are several), click on the textbox under "Parameters" and type: -Xmx###M

:'''Macintosh''':

::Under /Applications/Utilities/Java/J2SE 5.0/Java Preferences, look for the place to put the -Xmx###M
::Or look in the [[Solving_Java_Problems#Java_Control_Panel|Java Control Panel]].

Note that this is a local setting, so it will only affect that computer. You cannot expect that visitors of your web pages will have the same Java memory configuration as you, so be careful when using this feature.

Technical details:
* -Xmx sets the maximum memory heap size.
* -Xms sets the minimum memory heap size.

See also [[Jmol_Application#Giving_Jmol_more_memory_to_work_with|the procedure for the application]].

===  Forcing JmolApplet to open in a certain language ===
JmolApplet includes several languages (technically called localizations) for the user interface (pop-up menu).
JmolApplet will open by default with the interface using the language
of your operating system <ref>http://java.sun.com/j2se/corejava/intl/reference/faqs/index.html#set-default-locale </ref>. However, if you need to change this:

# Starting Jmol 11.1.30, the language in the applet can be switched anytime, from the pop-up  menu, "Language" item near the bottom.
# Or, using the scripting language: <code> language = "de" </code> (you must use the keyword "language" and the two-letter language code: ca, cs, de, en, es, et, fr, nl, pt, tr)
# ''This is an old method, only needed for versions below 11.1.30:'' If you want to force a certain language, 
<blockquote>
  <blockquote>
'''On Windows''':
Open Windows Control Panel > Java icon (opens Java Control Panel) > Java tab > Applet run-time configuration > Show button > 
on row "JRE", click on the textbox under "Parameters" and type:
<pre>
   java -Duser.language=es    # forces Spanish (EspaÃ±ol)
   java -Duser.language=de    # forces German (Deutsch)
   java -Duser.language=en    # forces English
   etc.
</pre>
  </blockquote>
  <blockquote>
'''On Macintosh''':
Open the Java Control Panel at /Applications/Utilities/Java/J2SE 5.0/Java Preferences and set the parameter as above.
  </blockquote>
</blockquote>

See also [[Jmol_Application#Forcing_Jmol_to_open_in_a_certain_language|the procedure for the application]].


<hr width=30%>
<references/>

== Jmol in Wikis ==

The applet can be embedded in [[wikipedia:HTML|HTML]] (or XHTML) pages (examples are listed on [[Websites Using Jmol]]), but also, with some extra technologies, in Wiki pages (see [[Jmol Processor]]).

== Unsigned vs. Signed Applet & Data Access ==

The '''signed''' applet can load a molecular model from any http or ftp URL. However, the user will be asked to trust the signed applet. This could be problematic since the publishing authority (jmol.org) "cannot be verified", and the security certificate was issued by a group that is "not trusted" (jmol.org). This is because it would be costly and cumbersome for each version of the applet to be signed by a trusted (commercial) authority.

The '''unsigned''' applet displays the molecule without asking the user to trust it. However, it is limited (for security reasons) to loading molecular models from the same http domain (server) that downloads the applet itself. [http://firstglance.jmol.org/ FirstGlance in Jmol] uses the unsigned applet by default, but the signed applet will be used when that "Advanced Option" is checked. Thus you can easily see both applets in action. Methods for accessing data files from arbitrary servers are described in some detail at [http://bioinformatics.org/firstglance/fgij/datameth.htm PDB Data File Access Methods].
<br>
If you are ''not'' running the applet from any server, i.e., you are using a web page residing in a '''local disk''', further security restrictions are applied by Java: molecular models can only be located in the same folder/directory as the applet files or below it; read [[Jmol Applet Deployment Local]].

== Tools for Authoring Jmol Web Pages ==
If you are not comfortable writing html/xhtml and javascript code or would just like to quickly put together some simple pages look at the export to web function of Jmol (available in version 11.4 and above).  This allows you to export all the necessary files to make simple pages that have a number of live Jmol displays or a single Jmol display that can be changed by clicking buttons.  You select the views you want the user to see by setting them up in Jmol.  You then add any desired text or comments to the .html file created by the export function in your favorite web editor (Some open source suggestions: [http://www.seamonkey-project.org/ SeaMonkey] is simple and works very well, [http://www.kompozer.net/ Kompozer] is more sophisticated and works pretty well, [http://www.w3.org/Amaya/ Amaya] is the most sophisticated but is harder to use). Instructions for using the export function are accessible in the export to web dialog within the Jmol application.  A more detailed tutorial and some older packages are available at [http://www.uwosh.edu/faculty_staff/gutow/Jmol_Web_Page_Maker/Jmol_Web_Page_Maker.shtml Jmol Web Page Maker].--[[User:Gutow|Gutow]] 21:48, 25 July 2008 (CEST)

== Saving Files from the Applet ==
Although this isn't obvious, the molecule that is being shown in the applet can be saved to local disk. To do so:
# Open applet's menu (right-click, Ctrl+click, or click on bottom-right "Jmol" logo).
# Click on topmost entry (name of molecule).
# On the submenu that appears, click on bottommost entry (name of file).
# Depending on your browser's configuration, the file will be opened in the associated program ("helper application") or you will get an "Open or Save" dialog; choose Save and location in your disk.

:''Warning'': At least in Windows, modern browsers may detect this action as opening a pop-up window, so it's likely that the pop-up blocker will prevent you from seeing the "Open or Save" dialog. Pay attention to messages and options in your browser to allow pop-ups for the current page. (Such messages often appear as yellow bars at the top of the page, warnings in a toolbar, or hints in the status line at the bottom of the browser window.)

:''Note for Chime users'': If you have MDL Chime installed, the molecule will be opened in a browser window using Chime. You just have to use Chime's menu (File > Save molecule as) to save the file to disk.

More user-friendly ways or saving files from JmolApplet are being considered by the developers.

In Jmol v.11, a part of the molecule can be extracted and saved into MOL format. This is not so straightforward as the former, and is described in the "interactive scripting documentation" (see [http://jmol.org/ Jmol home page]).

The ability to save the state of the molecule (rendering style, coloring, visibility, orientation, etc.) is under development, and already partially implemented in Jmol 11.0. See [http://www.stolaf.edu/academics/chemapps/jmol/docs/?ver=11.0#save <code>save state</code>] and [http://www.stolaf.edu/academics/chemapps/jmol/docs/?ver=11.0#write <code>write state</code>] in the Jmol scripting documentation. This will give similar functionality to what can be done in Chime or Rasmol, although due to Java security restrictions, saving to a file is not available for JmolApplet.