Scarlet Line home page Scarlet Line - SOFTWARE DESIGN & DEVELOPMENT

[Home]->[Documentation]->[Molecular Viewer]->[User's Guide]->[Usage]

Expand All
Collapse All
Contents

Using the Molecular Viewer Plugin Locate in Contents

The Molecular Viewer plugin works with most popular combinations of browser and operating system to display molecules which have been stored in one of over thirty different chemical file formats.

For users of a web browser who wish to be able to see molecules which have been embedded into web pages, please go to the download page to install the plugin version appropriate to their browser and operating system. Currently over thirty of the most popular combinations are supported.

Context Menu Locate in Contents

If you right-click a molecular view window, you will see the context menu. This has entries for the more common scriptable functions such as changing the view, or controlling animation.

How to include molecules in a web page Locate in Contents

A wide variety of syntax is supported, so that existing web pages need not be changed in order for molecules embedded in them to be displayed correctly. This includes many varieties of HTML and RasMol conventions. For new web pages, however, <object> tag syntax and javascript scripting are recommended.

The follwing examples assume that you have a file called water.cml in the same directory as the web page, and that it is in cml format. Please substitute the url to your molecule file in the data attribute, and set the MIME type in the type attribute.

Here is a simple example:

<object data="water.cml" type="chemical/x-cml" width="640" height="480" />

Note the use of the <object> tag instead of the deprecated <applet> or <embed> syntax. embed will also work, as shown below, but <object> is recommended to work with standard HTML in current and future browsers.

The data parameter is a url to a file containing the molecular data. In the example it is hosted locally. You can alternatively embed the molecular data in the web page directly ( see below ) or submit your molecular data to a standard repository, such as the Protein Data Bank or GenBank and then refer to the submitted data in the url.

The required type parameter states the format of the molecular data. Thirty different MIME types are supported, the details of which are on the Supported MIME Types page

The width and height parameters set the size of the molecular view window within the web page. They are required, because many browsers will simply not display anything otherwise. Note that they can be a number of pixels, such as width="640" height="480", or they may be percentages of the enclosing object, such as width="100%" height="60%".

Here is an example which sets some optional parameters:

<object data="water.cml" type="chemical/x-cml" width="640" height="480">
    <param name="bgcolor" value="grey"/>
    <param name="caption" value="water"/>
</object>

If you wish to make it easier for your visitors to install Scarlet Line Molecular Viewer, you can add the following parameter and inclusion to your <object> tag ( note that the width and height of the table should match the object ):

    <param name="pluginspage" value="http://www.scarletline.com/npcml/download.html"/>
    <a href="http://www.scarletline.com/npcml/download.html"
       title="Click here to download plugin.">
       <table frame="border" width="640" height="480">
          <tr><td valign="top"><img src="http://www.scarletline.com/img/plugin.png"
             width="196" height="60" alt="Click here to download plugin."/></td></tr>
       </table>
    </a>

Using the embed Tag Locate in Contents

Here is the same example if you wish to use embed instead of object syntax:

<embed src="water.cml" type="chemical/x-cml" 
    width="800" height="600" bgcolor="grey" caption="water"/>

Note that the data parameter is called src in an <embed> tag, and the type parameter is unchanged. All of the other parameters, which are param in an <object> tag can be simply included as attributes of the <embed> tag itself.

If you wish to make it easier for your visitors to install Scarlet Line Molecular Viewer, you can add the following attribute to your <embed> tag:

   pluginspage="http://www.scarletline.com/npcml/download.html"

Using the Full Browser Window Locate in Contents

If you wish to provide a link, which when clicked will display the molecule to fill the entire browser window, you simply use the a tag.
Here is the same example if you wish to use a href= instead of object data= syntax:

<a href="water.cml" type="chemical/x-cml">Display the molecule using the entire browser window</a>

Note that the object's data parameter is renamed href in an <a> tag, and the type parameter is unchanged. All of the other parameters are unused and can be removed.

Including the Data Inline Locate in Contents

You need not keep your molecular data in a seperate file, but can simply embed it directly into the html page. Here is an example:

<object type="chemical/x-xyz" width="800" height="600">
    <param name="inline" value="3&#xA;
Water&#xA;
O  4.013   0.831  -9.083&#xA;
H  4.941   0.844  -8.837&#xA;
H  3.750  -0.068  -9.293&#xA;
"/>
</object>

Note that there is no data attribute, as no external data is needed. Note also that &#xA; is used for new-line within the data, as html does not preserve the new-lines otherwise. If you need "tab" in your file format, it is &#x9;.

How to use Scripting Locate in Contents

The plugin accepts various ways of scripting, in order to support the variety of existing ways in which scripts are used with molecular display, such as RasMol, MDL Chime and Jmol. It is recommended that newly authored web pages use javascript as in the following examples.

Here is a simple example of a script which sets the background colour of a molecular view:

<object id="molview1" data="water.cml" type="chemical/x-cml" width="800" height="600" />
<script type="text/javascript">
   var molview1 = document.getElementById('molview1');
   molview1.bgcolor = "red";
</script>

You can see the above example working here: Molecular Viewer Basic Scripting

You will see that we now give an id attribute to the <object> tag, so that we can refer to this particular instance of an object. Each object should have a unique id, such as molview1, molview2, ....

In the script we create a variable which references the object, and then we can get or set properties, and call functions on the object. The script example simply turns the background red immediately. In a real script you are more likely to use the commands inside a function, maybe attached to a button.

Parameters and Functions Locate in Contents

The molecular viewer plugin supports one very large set of parameters and functions. The list includes many aliases and different ways of doing the same thing. For example, the following properties and functions all access the background colour:

  • background [property]
  • bgcolor [property]
  • bgcolour [property]
  • set_background [function]
  • set_bgcolor [function]
  • set_bgcolour [function]

The same list is used in all the various ways of interacting with molecular views, such as the <object> <param> attributes, the <embed> attributes, javascript properties and functions and rasmol scripts. The complete list can be seen in the Script Reference.

This great flexibility in scripting and naming supports the variety of existing ways in which molecular viewing has been set up.

Legacy "application/x-spt" Scripts Locate in Contents

Chime introduced another MIME type to handle buttons, here are some examples: Chime Button Tutorial. In standard html, button scripting is handled using html and javascript.

These buttons need to be modified to use html javascript conventions. Usually this simply means creating an html input type="button", and setting it's onclick attribute to point to a javascript function which mimics the original script attribute.

Here is a simple example of a legacy script. It shows an embedded molecule, followed by a single push button, which when pressed will change the background colour and zoom in.

<EMBED src="atcg.pdb" width=640 height=480 name="molecule">

<EMBED type="application/x-spt" width=15 height=15 button="push"
       target="molecule" 
       script="
background [xffffff]; 
delay .2;
zoom;						
	">

Here is the same example, with the minimum changes necessary to make it work without needing the Chime plugin. Please note that the name= attribute becomes id= in the embedded molecule.

<EMBED src="atcg.pdb" width=640 height=480 id="molecule">

<form>
   <input type="button" width=15 height=15 value="run script" onclick='document.getElementById("molecule").script("
background [xffffff]; 
delay .2;
zoom;						
   ")' />
</form>

And finally here is the same example corrected to use modern standard html:

<object src="atcg.pdb" type="chemical/x-pdb" width="640" height="480" id="molecule"/>

<script type="text/javascript">
   function button_script()
      {
      var molecule = document.getElementById('molecule');
      molecule.bgcolour = 'white';
      molecule.zoom();
      }
</script>
<form>
   <input type="button" value="run script" onclick='button_script()' />
</form>

Animation Locate in Contents

If a molecular model file contains more than one set of molecular data, then each set will be treated as a separate frame in an animation. Here is an example: Molecular Viewer Animation

Interesting Example Pages Locate in Contents

Sites to Visit Locate in Contents

There are many web sites which embed molecules in their pages. Unfortunately, due to the lack of a capable cross-platform plug-in for so long, many have switched to embedding java <applet> jmol code in place of the standard <object> format.