|
|
| (10 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | This page will summarize discussions on the jmol-user mailing list on how | + | This page summarizes some advice on how JSmol within web pages can be used to work from a local disk (<code>file://</code> protocol), instead of from a web server (<code>http://</code> protocol). |
| − | Jmol should be installed to work from a local hard disk or CD, instead of from
| |
| − | a web server. | |
| | | | |
| − | = Update note =
| + | This section is in relation to JSmol, versions 14 and later, particularly. It only relates to HTML5 file access, and only to files loaded using script commands such as <code>load</code> and <code>script</code>. |
| | | | |
| − | Much of what is on this page is pre-JSmol. jmolInitialize() is not used anymore.
| + | Note that you can prompt the page visitor for a local file by using the Jmol script command <code>load ?</code> or a URL using <code>load <nowiki>http://?</nowiki></code>. |
| − | | |
| − | = Browser considerations for local file access (JSmol) =
| |
| − | | |
| − | This section is in relation to JSmol, Ver. 14.x, particularly.
| |
| − | | |
| − | JSmol will handle much of the details for local file access. If using Java, be sure to use the all-permissions ("signed") applet. That is, in the Info parameter for Jmol.getApplet(name,Info), use <b>jarFile:"JmolAppletSigned0.jar", isSigned: true</b>.
| |
| − | | |
| − | Note that you can prompt the page visitor for a local file by using the Jmol script command <b>load ?</b> or a URL using <b>load <nowiki>http://?</nowiki></b>. | |
| | | | |
| | == Specific browser considerations == | | == Specific browser considerations == |
| | | | |
| − | === Firefox/Windows === | + | === 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 file access. JSmol will not run in MSIE locally.
| |
| − | | |
| − | === Chrome/Windows ===
| |
| − | | |
| − | No binary file access. For non-binary files, start Chrome using the command-line flag <b>--allow-file-access-from-files</b> for local file access.
| |
| − | | |
| − | === Opera/Windows ===
| |
| − | TODO
| |
| − | | |
| − | === Firefox/Mac ===
| |
| − | TODO
| |
| − | | |
| − | === Chrome/Mac ===
| |
| − | TODO
| |
| − | | |
| − | === Safari/Mac ===
| |
| − | TODO
| |
| − | | |
| − | = Rules for first-time user developing Jmol pages that will run from local disk: =
| |
| − | | |
| − | == Method (a) ==
| |
| − | Use pages only from a web server.
| |
| − | For testing purposes, you may wish to install a local web server on your computer.
| |
| − | | |
| − | == Method (b) ==
| |
| − | ''This works both locally and on the web server; depends on Java security rules, which might change in a future.'' <br />
| |
| − | ''Update:'' recent versions of Java and browsers (particularly Firefox) apply a more restrictive policy, affecting also the location of html files -- A better description is planned; for now, see the graphic examples below.
| |
| − | | |
| − | Molecule files (e.g. <tt>.pdb</tt>, <tt>.mol</tt>) must be in the same folder as the applet files or below it (in a subfolder).
| |
| − | | |
| − | Valid examples (see also graphic examples below):
| |
| − | | |
| − | 1.- Put {{File|Jmol.js}} and the set of {{File|JmolApplet0*.jar}} files on the top folder level of your website; then, for a page in a subfolder:
| |
| − | <html>
| |
| − | <head>
| |
| − | <script type="text/javascript" src="../Jmol.js"></script>
| |
| − | </head>
| |
| − | <body>
| |
| − | <script type="text/javascript">
| |
| − | jmolInitialize("../");
| |
| − | jmolApplet(200, "load caffeine.xyz");
| |
| − | </script>
| |
| − | </body>
| |
| − | </html>
| |
| − | | |
| − | 2.- Same for a page in a subfolder two levels below:
| |
| − | <html>
| |
| − | <head>
| |
| − | <script type="text/javascript" src="../../Jmol.js"></script>
| |
| − | </head>
| |
| − | <body>
| |
| − | <script type="text/javascript">
| |
| − | jmolInitialize("../../");
| |
| − | jmolApplet(200, "load caffeine.xyz");
| |
| − | </script>
| |
| − | </body>
| |
| − | </html>
| |
| − | | |
| − | 3.- Same as (1) but the model file is in a subfolder (named e.g. 'models') below the page itself:
| |
| − | <html>
| |
| − | <head>
| |
| − | <script type="text/javascript" src="../Jmol.js"></script>
| |
| − | </head>
| |
| − | <body>
| |
| − | <script type="text/javascript">
| |
| − | jmolInitialize("../");
| |
| − | jmolApplet(200, "load models/caffeine.xyz");
| |
| − | </script>
| |
| − | </body>
| |
| − | </html>
| |
| − | | |
| − | == Method (c) ==
| |
| − | ''This works both locally and on the web server.''
| |
| − | | |
| − | Use the "signed applet" files, {{File|JmolAppletSigned0*.jar}},
| |
| − | also included in the Jmol distribution [http://sourceforge.net/project/showfiles.php?group_id=23629 download page]
| |
| − | | |
| − | You can put applet files, model files and page files wherever you want to.
| |
| − | | |
| − | The users will receive a security warning from Java asking whether they accept the use of the signed applet (this may deter novice users from entering your pages, unless you first give them precise advice that this will show up and it is not harmful).
| |
| − | | |
| − | = Examples of folder arrangement =
| |
| − | | |
| − | This applies to running '''Jmol unsigned applet''' ({{File|JmolApplet0*.jar}} files) in '''local''' disks successfully (i.e. without Java security errors).
| |
| − | Recent (June 2010) Java and browser security policies are considered in these examples.
| |
| − | | |
| − | If pages are run from a web server, any folder arrangement should work; these examples and explanations only apply to local disk.
| |
| − | : ''Note'': there are now reports that even from a web server some folder setups may raise Java security errors too. If so, please try activating [[#Activating_UseCommandThread|UseCommandThread]] and share your findings in the email list.
| |
| − | | |
| − | === Jmol parent, models same ===
| |
| − | [[File:No_Problem.png]] These layouts give no problems.
| |
| − | <table cellspacing="0" cellpadding="0">
| |
| − | <tr><th>P</th>
| |
| − | <td width="42">[[File:Folder_yellow_open.png]]</td>
| |
| − | <td width="42"></td><td width="42"></td>
| |
| − | <td> JmolApplet jar files</td>
| |
| − | </tr>
| |
| − | <tr><th>X</th>
| |
| − | <td>[[File:Line42-down-branch-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> html files, model and script files</td>
| |
| − | </tr>
| |
| − | <tr><th>C</th>
| |
| − | <td>[[File:Line42-down.png]]</td>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | </tr>
| |
| − | <tr><th>S</th>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td><td></td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | <table cellspacing="0" cellpadding="0">
| |
| − | <tr><th>P</th>
| |
| − | <td width="42">[[File:Folder_yellow_open.png]]</td>
| |
| − | <td width="42"></td><td width="42"></td>
| |
| − | <td> JmolApplet jar files</td>
| |
| − | </tr>
| |
| − | <tr><th>X</th>
| |
| − | <td>[[File:Line42-down-branch-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td><td></td>
| |
| − | </tr>
| |
| − | <tr><th>C</th>
| |
| − | <td>[[File:Line42-down.png]]</td>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td> html files, model and script files</td>
| |
| − | </tr>
| |
| − | <tr><th>S</th>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td><td></td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | === Jmol parent, models child ===
| |
| − | [[File:No_Problem.png]] This layout gives no problems.
| |
| − | <table cellspacing="0" cellpadding="0">
| |
| − | <tr><th>P</th>
| |
| − | <td width="42">[[File:Folder_yellow_open.png]]</td>
| |
| − | <td width="42"></td><td width="42"></td>
| |
| − | <td> JmolApplet jar files</td>
| |
| − | </tr>
| |
| − | <tr><th>X</th>
| |
| − | <td>[[File:Line42-down-branch-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> html files</td>
| |
| − | </tr>
| |
| − | <tr><th>C</th>
| |
| − | <td>[[File:Line42-down.png]]</td>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td> model and script files </td>
| |
| − | </tr>
| |
| − | <tr><th>S</th>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td><td></td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | === Jmol parent, models sibling ===
| |
| − | [[File:Warning.png]] This layout may be used from local disk, only
| |
| − | if you activate <code>UseCommandThread</code> in your page (see details [[Jmol_Applet_Deployment_Local#Activating_UseCommandThread|below]]). This may also apply to pages run from a server.
| |
| − | | |
| − | <table cellspacing="0" cellpadding="0">
| |
| − | <tr><th>P</th>
| |
| − | <td width="42">[[File:Folder_yellow_open.png]]</td>
| |
| − | <td width="42"></td><td width="42"></td>
| |
| − | <td> JmolApplet jar files</td>
| |
| − | </tr>
| |
| − | <tr><th>X</th>
| |
| − | <td>[[File:Line42-down-branch-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> html files</td>
| |
| − | </tr>
| |
| − | <tr><th>C</th>
| |
| − | <td>[[File:Line42-down.png]]</td>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | </tr>
| |
| − | <tr><th>S</th>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> model and script files</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | === Jmol sibling, models same ===
| |
| − | [[File:Error-Forbidden.png]] This layout cannot be used from local disk.
| |
| − | <table cellspacing="0" cellpadding="0">
| |
| − | <tr><th>P</th>
| |
| − | <td width="42">[[File:Folder_yellow_open.png]]</td>
| |
| − | <td width="42"></td><td width="42"></td><td></td>
| |
| − | </tr>
| |
| − | <tr><th>X</th>
| |
| − | <td>[[File:Line42-down-branch-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> html files, model and script files</td>
| |
| − | </tr>
| |
| − | <tr><th>C</th>
| |
| − | <td>[[File:Line42-down.png]]</td>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | </tr>
| |
| − | <tr><th>S</th>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> JmolApplet jar files</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | === Jmol sibling, models sibling ===
| |
| − | [[File:Warning.png]] This layout may be used from local disk, only
| |
| − | if you activate <code>UseCommandThread=true</code> in your page (see details [[Jmol_Applet_Deployment_Local#Activating_UseCommandThread|below]]). This may also apply to pages run from a server.
| |
| − | | |
| − | <table cellspacing="0" cellpadding="0">
| |
| − | <tr><th>P</th>
| |
| − | <td width="42">[[File:Folder_yellow_open.png]]</td>
| |
| − | <td width="42"></td><td width="42"></td><td></td>
| |
| − | </tr>
| |
| − | <tr><th>X</th>
| |
| − | <td>[[File:Line42-down-branch-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> html files</td>
| |
| − | </tr>
| |
| − | <tr><th>C</th>
| |
| − | <td>[[File:Line42-down.png]]</td>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | </tr>
| |
| − | <tr><th>S</th>
| |
| − | <td>[[File:Line42-down-right.png]]</td>
| |
| − | <td>[[File:Folder_yellow_open.png]]</td>
| |
| − | <td></td>
| |
| − | <td> JmolApplet jar files, model and script files</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | = Additional methods =
| |
| − | | |
| − | == Conditional use of the signed applet ==
| |
| − | <!-- posted by René Kanters -->
| |
| − | In order to have the applet used be signed or not signed depending on whether you are serving the pages from a server or testing them locally, one can use the following construct for the initialization:
| |
| − | | |
| − | jmolInitialize("../../Jmol", window.location.protocol=="file:");
| |
| − | // use the signed applet if needed
| |
| − | | |
| − | == Activating UseCommandThread ==
| |
| − | This Jmol parameter defines whether some commands coming from the page UI controls (like a jmolButton) use or not a different thread. As a consequence, the Jmol script commands coming from the UI controls may be denied access to files by Java security policy.
| |
| − | | |
| − | Setting this ''on'' (or ''true'') avoids some Java security locks, such as loading a file from a folder different to the one the html page is in (but the rule 'model files together or below the Jmol files' must still be satisfied). Use it like this:
| |
| − | jmolSetCallback("UseCommandThread","true")
| |
| − | or like this:
| |
| − | jmolSetParameter("UseCommandThread","true")
| |
| − | Either one must go after <code>jmolInitialize()</code> and before <code>jmolApplet()</code>. Case of the "UseCommandThread" text is irrelevant (e.g. "useCommandThread" or "usecommandthread" will also work).
| |
| − | | |
| − | = Comments =
| |
| | | | |
| − | From Bob Hanson:
| + | You will be able to read both binary and text files locally, but it is necessary to change the default setting: |
| | + | *navigate to <code>about:config</code>, find the <code>security.fileuri.strict_origin_policy</code> entry and set it <code>false</code>. |
| | | | |
| − | I believe the rule is simply this:
| + | Despite this, there may be occasions where access fails with errors, depending of the folder location of files composing the page and the JSmol library. (No certain description of setups that fail has been found yet) |
| | | | |
| − | On a hard drive, all files opened by the applet (model or otherwise)
| + | === Chrome / Windows === |
| − | must be in the same directory or a subdirectory of the {{File|.jar}} file.
| |
| | | | |
| − | The only problem comes if you place the {{File|.jar}} file in some other subdirectory | + | The old method of starting Chrome using the command-line flag <code>--allow-file-access-from-files</code> for local file access is no longer possible. |
| − | not somewhere on the "path" to the model file. Then the page might work if
| |
| − | uploaded to a server, but won't work on your local machine in <tt>file:///</tt> mode.
| |
| | | | |
| − | Nick Greeves provides this screen shot of his directory structure, where
| + | The only likely solution if you wish to use Chrome is to set-up a local web server (read below). |
| − | you can see how he has {{File|caffeine.xyz.gz}} in the {{Directory|model}} subdirectory of the {{Directory|jmol}} directory, | |
| − | where {{File|JmolApplet.jar}} is found.
| |
| | | | |
| − | [[Image:Local_Directory_Structure.png]]
| + | It is '''not''' possible to load local '''binary''' files 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 |
| | | | |
| − | HTML, JS, IMG files -- all these can be anywhere,
| + | This does not apply to files drag-dropped onto JSmol or files loaded using "?", which use the HTML5 FileReader object. That method reads binary files without a problem. |
| − | including on totally different servers.
| |
| | | | |
| − | So, if this is important to you, place the {{File|.jar}} file in the TOP subdirectory
| + | === Edge / Windows === |
| − | of your project, and there will be no problem. (I am not recommending placing the {{File|.jar}} file in {{Directory|c:\}})
| |
| | | | |
| | + | Situation is the same as for Chrome (pending confirmation) |
| | | | |
| − | ---------- | + | === Opera / Windows === |
| | + | to-do |
| | | | |
| − | From Nick Greeves:
| + | === Firefox / Mac === |
| | + | to-do |
| | | | |
| − | For the record here's the source of {{File|WorksFromaCD.html}} that shows the paths.
| + | === Chrome / Mac === |
| | + | to-do |
| | | | |
| − | <html>
| + | === Safari / Mac === |
| − | <head>
| + | to-do |
| − | <title>Simple example</title>
| |
| − | <script src="Jmol.js"></script>
| |
| − | </head>
| |
| − | <body>
| |
| − | <script>
| |
| − | jmolInitialize("../jmol");
| |
| − | jmolApplet(200, "load model/caffeine.xyz.gz");
| |
| − | </script>
| |
| − | </body>
| |
| − | </html>
| |
| | | | |
| | + | == Using a local web server == |
| | + | Several packages are available that will install a local server in your system. You will then be able to access your local pages and molecule files by activaning such server and access the pages via <code>localhost:</code> or <code><nowiki>http://127.0.0.1/</nowiki></code> protocols. |
| | | | |
| − | ----------
| + | This removes any limitations in accessing files. Note that for binary files, at least with some browsers, you need to configure the <code>serverURL</code> item in the [[Jmol_JavaScript_Object/Info#Files_and_paths|<code>Info</code> variable]] to use the PHP filter, likely from the same server. |
| | | | |
| − | From [[User:AngelHerraez|Angel Herráez]]:
| + | As an easier alternative, there seems to be some extensions for the Chrome browser that will act as local server. Compatibility with latest Chrome security policies has not been checked. |
| − | Nick, I think although your example is correct, it will mislead people. There is no need for a {{Directory|jmol}} folder. Your code should be
| |
| | | | |
| − | jmolInitialize("./");
| + | == Legacy documentation == |
| | + | Mainly involving use of Jmol Java Applets in web pages (not supported by current web browsers) |
| | | | |
| − | since the applet is in the same directory/folder as the html page.
| + | See the [[Special:PermanentLink/8397|old version of this page]]. |
| − | Even "" might work the same as "{{Directory|./}}"
| |
This page summarizes some advice on how JSmol within web pages can be used to work from a local disk (file:// protocol), instead of from a web server (http:// protocol).
This section is in relation to JSmol, versions 14 and later, particularly. It only relates to HTML5 file access, and only to files loaded using script commands such as load and script.
Note that you can prompt the page visitor for a local file by using the Jmol script command load ? or a URL using load http://?.
Specific browser considerations
Firefox / Windows
You will be able to read both binary and text files locally, but it is necessary to change the default setting:
- navigate to
about:config, find the security.fileuri.strict_origin_policy entry and set it false.
Despite this, there may be occasions where access fails with errors, depending of the folder location of files composing the page and the JSmol library. (No certain description of setups that fail has been found yet)
Chrome / Windows
The old method of starting Chrome using the command-line flag --allow-file-access-from-files for local file access is no longer possible.
The only likely solution if you wish to use Chrome is to set-up a local web server (read below).
It is not possible to load local binary files 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 JSmol or files loaded using "?", which use the HTML5 FileReader object. That method reads binary files without a problem.
Edge / Windows
Situation is the same as for Chrome (pending confirmation)
Opera / Windows
to-do
Firefox / Mac
to-do
Chrome / Mac
to-do
Safari / Mac
to-do
Using a local web server
Several packages are available that will install a local server in your system. You will then be able to access your local pages and molecule files by activaning such server and access the pages via localhost: or http://127.0.0.1/ protocols.
This removes any limitations in accessing files. Note that for binary files, at least with some browsers, you need to configure the serverURL item in the Info variable to use the PHP filter, likely from the same server.
As an easier alternative, there seems to be some extensions for the Chrome browser that will act as local server. Compatibility with latest Chrome security policies has not been checked.
Legacy documentation
Mainly involving use of Jmol Java Applets in web pages (not supported by current web browsers)
See the old version of this page.
