MW applets and MWScript-JavaScript interactions

Now that you can publish a Molecular Workbench simulation as an applet and embed it on your web page, you may be wondering how you can control it and get data in and out. It may be interesting for web developers who would like to link an existing Flash animation with a molecular dynamics simulation in MW. For example, when the visitor clicks something in the Flash animation, a molecular dynamics simulation will pop out to show the molecular mechanism of what is going on underneath.

With MW, this can now be done using MWScript and JavaScript. MWScript is a scripting language used in MW to support modelers and animators to design simulations. The model builders in MW do have some simple GUI for building models and designing simulations, but their functionality is limited (as with any GUI). Syntactically, MWScript is a cousin of JmolScript, which supports scripting with the popular Jmol molecular viewer. So anyone who is already familiar with JmolScript may find it easy.

Before we talk about scripting, let me show you how to set up an MW applet on your web page. If you just want to show an existing MW simulation from mw2.concord.org (which hosts MW) on your web page, just embed the following applet code within the body of your HTML file:

<applet id="applet_id"
archive="http://mw2.concord.org/public/lib/mwapplet.jar" 
code="org.concord.modeler.MwApplet" codebase="http://mw2.concord.org/public/" 
width="100%" height="500"> <param name="permissions" value="all-permissions"/> 
<param name="script" value=
"page:0:import http://mw2.concord.org/public/student/classic/motion/undershotwaterwheel.cml"/>
</applet>

In the above example, I have randomly chosen an existing simulation from MW to show how this works. If you want to show other simulations, just replace "http://mw2.concord.org/public/student/classic/motion/undershotwaterwheel.cml" with whatever else.

This following shows the embedded MW applet specified by the above code:





This is very easy to do. But it has a limitation. Suppose you have created an MW simulation of your own and the name of the main file is "simulation.cml" (an MW simulation has other files associated with it as well). Now you have to upload the files to the Web. If you use its URL in the embedding code, the MW applet will not load it. Because of a good security reason, an applet is allowed to read files from only the same code base where the Java executable is located (in this case, http://mw2.concord.org/public/lib/mwapplet.jar).

To avoid this problem, you would want to have your own code base instead of using mw2.concord.org. First, you download the jar file: mwapplet.jar to the same folder where "simulation.cml" and the HTML file sit. Second, change the embedding code to:

<applet id="applet_id" archive="mwapplet.jar" 
code="org.concord.modeler.MwApplet"  codebase="http://mw2.concord.org/public/"
width="100%" height="450"> <param name="permissions" value="all-permissions"/> <param name="script"
value="page:0:import simulation.cml"/>
</applet>

Having done these, you just need to make sure to also upload "mwapplet.jar" to the same web folder where "simulation.cml" has been uploaded to.

If you have done these and succeeded in getting an MW applet to work properly, let's see how to get it to work with JavaScript as well. First, download this file: mw.js to the same folder. Second, put the following script declaration in the header of your HTML file:

<script type="text/javascript" src="mw.js"></script>

The MW applet is now ready to interact with JavaScript. The applet works offline as well, so you can conveniently test your JavaScript before deploying the whole thing to the Internet, by just double-clicking on the HTML file and see how it works.

There are currently three types of interactions between MWScript and JavaScript.

• Use JavaScript to send MWScript to control an MW applet
• Use JavaScript to feed data to an MW applet
• Use JavaScript to get data out of an MW applet

The runScript(id, script) method in mw.js can be used to send MWScript to an MW applet with the specified ID. An MW applet is an MW page that can have multiple models, though in practice you would only use one model per applet. To specify which model you would like to send the MWScript, you have to following the following protocol:

[model type]:[index or UID of model]:[script body]

For instance, mw2d:1:run instructs the first model within the MW applet to run. You can pass a variable from JavaScript to MWScript by concatenating the variable with a script command. For example, var temp = 300; runScript("applet_id", "mw2d:1:set temperature " + temp) sets the temperature of the system to be 300 K.

The get command in MWScript was specifically designed to fetch data out of an MW applet. For instance, you can get the temperature by using the following code: var temp = runScript("applet_id", "mw2d:1:get %temperature");.

This page demonstrates all these three types of interactions with one applet. It is inconvenient for me to mix code in this blog as it interferes with the blog's setup. When you go to that page, you can view the page source to see the JavaScript code. If you have Firebug, it can also be used to view the code easily.

For more information about MWScript, go to http://mw.concord.org to launch the standalone application and check out the "Script" section in the User's Manual.