PyMOL Web Services

• A summary of changes since the last update.
• An overview of the PyMOL HTTP server.
• A compact API reference with names and parameters for all exposed methods.
• Explanation of how PWG files are used to launch PyMOL with its HTTP Server.
• A discussion of the various request generation methods.
• Coverage of the same origin policy and how it impacts this interface.
• Tips on running the sample applications below.

Sample Mini-Applications

These sample applications will introduce you to the concepts needed to develop your own PyMOL web applications. They gradually move from simple to complex, demonstrating the various ways of integrating PyMOL into your own web infrastructure. If nothing happens when you click these links, please review the section on running them and consult the README.TXT file accompanying the distribution.

• Same Origin

  Where PyMOL is the only web server, and it serves all the ordinary http content as well as handling PyMOL-specific method requests.

  • Sample 01: is a simple validation application demonstrating the simplest-possible use case: static HTTP links targeting a separate frame. This application provides basic documentation for and validation of the core PyMOL web services API, but is probably not an example you should follow in developing your own applications.

  • Sample 02: is a slightly more sophisticated application which makes use of JavaScript to lighten the burden on the web developer. The response from PyMOL is directed to an embedded IFRAME on the page. Note that this approach is limited to issuing a single PyMOL request per DOM event. For this reason, we do not recommend using this approach except for trivial applications.

  • Sample 03: works much like Sample 02, but we have added the important extra convenience of a command queue bound to the IFRAME. This makes it possible to issue multiple PyMOL commands from JavaScript in response to a single DOM event. This application illustrates our recommended method for developing simple PyMOL web applications if minimal use of JavaScript is desired.

  • Sample 04: is a more complex same-origin structure table application which offers the user a series of buttons for toggling structures on and off, with various representations.

  • Sample 05 is a same-origin demonstration application which uses XmlHttpRequest objects to both make requests and receive JSON object responses back from PyMOL in a synchronous fashion. Note that this synchronous remote-procedure-call behavior is only possible under the same-origin scenario.

  • Sample 06: introduces our JavaScript API for PyMOL, which is based on wrapping XMLHttpRequests underneath JavaScript objects which expose an API for PyMOL very similar to that available from within Python. This sample runs synchronously. Please note that the pymol.js implementation included in this deliverable is preliminary and potentially subject to change. However, this will likely be the optimal approach for developing web-based PyMOL applications.

  • Sample 07: shows how an HTML FORM can be used with PyMOL Web Services. This allows one to use buttons, checkboxes and other INPUT elements of a FORM to deliver commands to PyMOL. It also shows how a file can be uploaded to PyMOL.

  • Sample 08: demonstrates how you can use the buffering features of the PyMOL JavaScript API to consolidate many method calls into a single request and thus achieve better performance and reliability.

• Multi Origin (Cross-Domain)

  Where web content is served from a remote web server and the web broswer is responsible for sending requests to a local PyMOL instance which operates its own web (HTTP) server for processing PyMOL-specific method requests.

  • Sample 11 introduces the multi-origin scenario, where the host and port number of the PyMOL server instance must be explicitly specified in the web page.

  • Sample 12 shows how a multi-origin application works using our JavaScript API. In the multi-origin scenario everything happens asynchronously, and so callbacks must be employed if your script is to act upon results obtained from PyMOL requests.

  • Sample 13 shows how you can instead use jQuery with the JSONP hack to do multi-origin scripting.

  • Sample 14 shows how you can use the buffering features of our JavaScript API to avoid problems with out-of-order method execution.

  • Sample 15 shows how you can use IFRAMEs to launch on or more PyMOL instances manually (at the user's request), instead of having it launch automatically, as in the previous examples.

  • Sample 16 covers the API functions for controlling buffering and explains how you can get the current buffer as a JSON-encoded string or URL for use with a separate JavaScript framework such as jQuery.

  Hopefully you now have enough information to start developing your own web content and applications which integrate PyMOL using the web services interface!

  The code for the applications above is located inside a series of folders located at:

  $PYMOL_PATH/modules/web/examples/sample*