Web Services - Sample 16: Control and use of the JavaScript API command buffer

quit pymol (FireFox only: view page source)

This example explains the use of the JavaScript API functions setBufferMode, getBufferJSON, getBufferURL and sendJSON. These allow you to:

set the command buffering mode on and off at any point in your JavaScript code.
retreive the current contents of the command buffer.
retrieve a URL containing the current command buffer.
send a JSON-encoded pymol command directly to PyMOL.

The setup of this example is just like sample 14: we use the multi-origin scenario, providing the host and port for the PyMOL server. In this example however, we call setBufferMode('on') in the function part1() instead of specifying the buffer mode when new PyMOL instance is created.

var pymol = new PyMOL('localhost',8086); // create PyMOL object instance for server of this page

var cmd = pymol.cmd; // assign a global symbol for the PyMOL cmd API

As in sample14, the two part cascade is started by calling the function part1. In this example's part1 function, the API function getBufferJSON() is called to return the JSON-encoded list of pymol commands contained in the buffer. This is simply displayed on the web page without further processing. Then the commmand is delivered to PyMOL using the sendJSON(process_chains, jcmd) function call, causing the callback to process_chains after the commands are executed by PyMOL.


function part1() {
    pymol.setBufferMode('on');
    cmd.reinitialize();
    cmd.load("$PYMOL_PATH/test/dat/1tii.pdb", "atestname");
    cmd.show_as("cartoon");
    cmd.get_chains("polymer");
    jcmd = pymol.getBufferJSON();
    show_message(jcmd);
    jurl = pymol.getBufferURL();
    show_message(jurl);
    pymol.sendJSON(process_chains, jcmd);
    pymol.setBufferMode('off');
}

Start this example by running part1.
The getBufferJSON and getBufferURL results appear below:

Possible uses for getBufferJSON and getBufferURL:
Sample 13 showed how a simple pymol command can be used with jQuery. In that example, the URL supplied to jQuery's getJSON function was a fixed string containing the pymol load command.

$(document).ready(function() {

  $("a[name=load]").click(function() {
    try {
      $.getJSON(host+"/apply/pymol.cmd.load?filename=$PYMOL_PATH/test/dat/pept.pdb&_callback=?", callback1);
    } catch (e) {
      alert(e);
    }
    return false; // causes the HREF to not load a new page
  });
});

Multiple pymol commands can be easily used with jQuery by setting command buffering on, issuing any JavaScript API pymol.cmd commands, and getting a valid URL using getBufferURL. This URL be used with jQuery's getJSON in a way analogous to sample 13. This frees you from having to construct individual pymol command strings, or to encode them into a valid URL.

$(document).ready(function() {

// this function assumes that a (global) pymol instance has already been created
//  and that there are already some commands in the command buffer.
  $("a[name=load]").click(function() {
    try {
      $.getJSON(host+pymol.getBufferURL()+"&_callback=?", callback1);
    } catch (e) {
      alert(e);
    }
    return false; // causes the HREF to not load a new page
  });
});