Introduction

This vignette is different from the others. There will be no interactive demonstrations of PhyloWidget; instead, we will discuss the various options open to developers for integrating PhyloWidget with their database, pipeline, or software.

Warning: this discussion may become very technical! If you are a non-technical user, you'd best bail out now before you get hurt. Of course, if you are interested in deploying PhyloWidget on your own site and get lost at any point, feel free to contact us.

Deployment: weighing your options

PhyloWidget was specifically designed to easily integrate with phylogenetic databases. Currently, PhyloWidget provides two main methods for integration:

• URL / Hyperlink API

  The URL API provides a simple, easy way to link to PhyloWidget in an automated manner. In order to link to PhyloWidget, you should first choose whether to use the "Full" or "Lite" version of the applet. The full version has a stable base URL of http://www.phylowidget.org/full/index.html, and the lite version can be found at http://www.phylowidget.org/lite/index.html.

  Constructing the query is then a very simple process of adding configuration parameters to the URL string. A few examples will clearly illustrate the basic syntax:

  http://www.phylowidget.org/lite/index.html?tree='(a,(b,c));'
http://www.phylowidget.org/lite/index.html?tree='(a,(b,c));'&search='a'
http://www.phylowidget.org/full/index.html?tree='(a,(b,c));'&search='a'&menus='none.xml'

  • Some words of caution: be careful with your parentheses! Javascript and HTML are notoriously sensitive to misuse of nested parentheses. This is often the source of the problem when PhyloWidget is apparently ignoring your URL queries.
  • Another useful tip: try using the target="_blank" attribute in your <A> elements to cause links to be opened in a new tab or wndow.

  For information on the various configuration parameters that can be used, we recommend you go directly to the (reasonably well-documented) source code:

  • Up-to-date documentation of PhyloWidget's configuration parameters.

• Direct Integration

  For more control and tighter integration, you may want to employ PhyloWidget within your own webpage or database as opposed to merely linking to our hosted version. Again, PhyloWidget makes this process easier than you might expect!

  For direct integration of PhyloWidget with your site, you have two options:

  Remote Hosting

  Remote hosting means that the PhyloWidget applet and scripts are hosted here, on PhyloWidget.org, and your website uses the remotely hosted files to load PhyloWidget into your webpage. The advantage of remote hosting are many:

  • Nothing to download or set up—just one line of Javascript and you're done
  • Constant access to the latest version of PhyloWidget, without having to re-download or update your files
  • Two words: quick and easy!

  To get up and running with a remotely-hosted PhyloWidget applet, include the following within your HTML <header> element:

  <script src="http://www.phylowidget.org/scripts/phylowidget.js"></script>

  This will cause the necessary Javascript functions to be loaded. The next step is to then choose between PhyloWidget Full or PhyloWidget Lite. This can be done by calling either of the two following Javascript functions from somewhere within your page:

  PhyloWidget.useFull(); // Use PhyloWidget Full PhyloWidget.useLite(); // Use PhyloWidget Lite

  Next, you can choose the configuration parameters to use when loading PhyloWidget. The available options are the same as for the URL API, except that here you can additionally specify the 'width' and 'height' of the applet:

  var params = { width:500, height:300, tree:'(a,(b,c));', search:'a' }; Finally, you choose how you want PhyloWidget to be loaded on your page: PhyloWidget.loadWidget('my_div',params); // Loads PhyloWidget into the element with ID of 'my_div' PhyloWidget.writeWidget(params); // Immediately inserts the applet code directly into the current document.

  To see an example of PhyloWidget's remote hosting in action (and to tinker with it yourself), visit the following testing page: PhyloWidget Testbed

  Local Hosting

  Local hosting is very much the same as remote hosting. The main difference is that in this case, you keep the required PhyloWidget code hosted on your own site. Also, when hosting the applet locally, you don't need to call the useFull() or useLite() functions to choose between the two options; this choice is made when you decide which version of the .jars to include.

  Access to the latest version of the PhyloWidget applets can be found in the Downloads section under "Entire project," or just click here (zip). Inside the .zip file, look under the web directory, and you should find two sub-directories, named full and lite. These directories exactly corresponded to the online versions of PhyloWidget Full and PhyloWidget Lite; in theory, you could drop either directory into your webserver and it will work without a problem.

  If you're hosting PhyloWidget on your own site, we will assume that you know how to navigate the required Javascript and HTML issues, so we will leave the rest to you.

Of course, if you have any problems at all, please don't hesitate to contact us!