Request Generation Methods

The original PyMOL web-services specification described only HTTP query-based requests for controlling PyMOL. In developing that interface, we achieved a better understanding of optimal web application structure and have consequently added two additional approaches for controlling PyMOL from a web page. Thus, there are now three different approaches to consider for generating requests:

  1. Simple HTTP Requests
  2. JSON-based AJAX Requests
  3. The PyMOL JavaScript API

Simple HTTP requests allow you to control PyMOL by embedding PyMOL commands in a URL or an HTML <FORM>. AJAX and API requests allow PyMOL control as well, but also allow you to receive results back from PyMOL. This capability can be used to develop interactive web applications, with certain limitations imposed by the browser and transport protocol.

Simple HTTP requests to PyMOL

The simplest way to control PyMOL from a web page is to make a simple HTTP request, for example with <A> links as shown in Sample 01 This approach is suitable for simple, "quick and dirty" web pages that don't need much flexibility or user interaction, except for clicking links. This might be suitable for writing a report that provides links that activate PyMOL and illustrate some results. Such a link might be written as:

<A HREF="/pymol.cmd.show?representation=sticks&selection=chain A">sticks</A>

There are other ways to make simple HTTP requests (Samples 02, 03, 04 and 07), for example by having a button click call a JavaScript function. Such a link might be written as:

<INPUT TYPE=BUTTON onClick='show_sticks("chain A")' NAME=sticks>

Using JavaScript allows for greater interactivity on the web page and could allow you to develop complete web applications to control PyMOL. However, simple HTTP requests, whether hard-coded into links or wrapped in JavaScript, only allow you to control PyMOL, not get results back. Results sent back from PyMOL can be displayed, say in an IFRAME, but simple HTTP approach does not enable you to dynamically change your web application in response to the results sent back from PyMOL.

AJAX requests to PyMOL

Using AJAX requires a bit more setup than simple HTTP requests, but opens up the possibility of real interaction with PyMOL. Using AJAX requests, you send PyMOL commands and also receive any results in JavaScript Object Notation (JSON). Using JavaScript, you can use those results to dynamically change your web application. There is sample code you can explore in Sample 05. You can also use JQuery and JSONP. They use an underlying AJAX approach entirely compatible with our PyMOL web server. This allows you to develop complex web applications with even greater ease and interactivity. The use of JQuery and JSONP is shown in Sample 13.

JavaScript API for PyMOL

The JavaScript API for PyMOL provides a new JavaScript Object, PyMOL. It contains functions that correspond to nearly 200 PyMOL commands via their Python method counterparts. While this API is still experimental, our goal is to provide a well-documented, stable interface to PyMOL that frees you from the underlying implementation details, such as AJAX. Using the API is as simple as including the pymol.js and json2.js scripts in your HTML documents and issuing PyMOL requests via simple native JavaScript statements.

The JavaScript API for PyMOL provides a new JavaScript Object type called PyMOL. Once a new instance of a PyMOL JavaScript object is created (here, named "pymol"): 

pymol = new PyMOL("localhost", 8081)
then 
pymol.cmd.show("sticks", "chain A")
in JavaScript works the same as if you had typed the command 
show sticks, chain A
into PyMOL or called the 
cmd.show("sticks", "chain A")
native Python method.