SMD’s Ontology Widget
Introduction Author: Catherine Beauheim Date: January 26, 2007 Revised: April 23, 2007 The Ontology Widget is a javascript/html application that utilizes ajax (asyncronous javascript and xml) to rapidly find and select ontology terms on a web page. The widget is intended to be part of a bigger context, such as an experiment annotation page. The javascript functions query the SMD Ontology Service to retrieve and navigate ontology terms quickly and easily. The first part of the document, System Architecture, briefly describes the environment in which the widget works. The next section, Behavior of the Ontology Widget, describes what the widget does. The third part explains how to construct an html page to use the widget. Appendix 1 is an example html page. Appendix 2 describes how to deploy the widget and Appendix 3 describes SMD Ontology Services in detail. The widget can be accessed from http://smd.stanford.edu/js/ontology/v1/ExampleProduction.html. The download site for the OntologyWidget is http://smd.stanford.edu/ontologyWidget. Here you can find the complete gzipped package that includes the war file, this document and the example html file. The javascript files are available at this site in a jar file.
Widget Context and Architecture
The Ontology Widget depends on three levels of service: the client user-interface in the browser, a client-side Tomcat servlet stub and http server, and the backend SMD Ontology Service and ontology database. In Figure 1, the browser interface is shown in gray, the client-side Tomcat server is shown in green and the SMD OntologyService is shown in blue. The browser displays an html file that calls javascript code to interprete user actions. User actions generate queries to the SMDOntology Service through a client-side servlet stub. The SMD Ontology Service has Java servlets that construct sql queries and direct the queries to our ontology database. The response from the database is packaged in an xml document that is passed back through the servlet stub to the javascript code. The javascript code interprets the xml document and draws html in the client‟s browser.
Figure 1. System Architecture The widget supports most of the OBO ontologies listed at http://obo.sourceforge.net/cgi-bin/table.cgi. A current list of our ontologies can be retrieved by directly querying our SMD Ontology Service at http://smd.stanford.edu/smd/OntologyService?func=getOntologyList. Queries to the SMD OntologyService are described in Appendix 3.
Behavior of the Ontology Widget
The widget is composed of a title, a label, a text field, a search button and a tree display. The tree display is an area reserved to display the ontology as a tree. Figure 2 shows one widget, as it would be displayed on a web page. In the text field, the user can type in characters to search for matching terms. The text field is connected to an auto-complete list of terms queried through the SMD Ontology Service. As the user types into the text field, the ontology database searches for terms that match the typed-in characters. The SMD Ontology Service returns a matching term list up to 50 terms. When the user selects a term from the list, it is written to the text field. Figure 3 shows the list that matches the characters „res‟.
Textfield
Title
Label
Physiological process is the term selected as the root of this tree and defined in the html file.
Figure 2. Ontology Widget with the Gene Ontology term Physiological Process selected as the root term in the html file.
Figure 3. Auto-complete list of terms matching „res‟ The tree display area shows the ontology as a hierarchical tree. Figure 4 shows the tree display for the children of Biological Process. Clicking on a term in the tree will highlight the term and write it to the text field. Figure 5 shows the homeostasis term highlighted in the tree and written to the text field. We also show paths in the tree from a selected term to the ontology root. To display a path, select a term from the auto-suggest list (as in Figure 3) or directly from the tree (as in Figure 5) and click the Search button.
Figure 4. Tree View of Biological Process
Figure 5. Selecting term in the tree writes it to the text area
The tree display is navigated using the common collapse and expand icons shown in Figure 6. The plus sign indicates that there are children of this term that are not displayed. Clicking the plus sign expands the tree node and shows the children. The minus sign collapses the tree at this node and hides the children.
Figure 6. Tree Navigation Icons The icon with three dots is displayed when we show the path from the tree root to the selected node, highlighted in yellow. Only the child node along the path is shown. The icon with three dots indicates that there are additional child nodes for this parent that are not being displayed. When the dot icon is clicked, the children of the term are displayed and the icon disappears. Figure 6 shows the ontology tree for Biological Process when the term “response to pheromone …” has been selected from the auto-complete list. Notice that the term, “response to pheronome …”, is highlighted in the tree and that the term occurs in the tree two times. The dots icon here shows that all the terms along the path from the root, physiological process, to “response to pheromone..” have more child terms that are not displayed.
Figure 6. Tree from selected term to root
The widget is designed to report five fields of data when a button of
is included on the form. The action method that is called will be supplied
by the user of the widget. Each widget will report its ontology name, the label, title, term name and term accession number through hidden input fields. We provide a sample action for Submit which reports the values in a simple table. In the section below we describe how to construct a web page with an ontology widget and a Submit button.
How To Construct a Webpage with Ontology Widgets
In this directory and as Appendix 1, we have created an html file which can be used as a template for widget creation. The basic outline of widget creation is that the html file must initialize the SMDService by calling a javascript function, SMDService(). The SMDService handles all the queries to the SMD Ontology Service through a proxy servlet and XMLHttpRequests and responses. Then the html file defines the widget parameters in JSON format (javascript object notation). When the widgets are configured, they are dynamically placed on the page at user-specified locations. Each widget will report five fields in hidden input fields when the form is submitted. Appendix I gives a full listing of an example html file. The html file is described in detail below.
HTML File Format: The section
Ontology Widget is constructed using seven javascript files plus icon image files and a cascading style sheet (css). The tree in the annotation widget is built using YAHOO!‟s public domain user interface code for widgets (http://developer.yahoo.com/yui ). It is not necessary to download the javascript files, but they are available from our web site. In Figure 8, the javascript and css files are imported into the html file by referencing the files on our web server. Improvements we make are automatically available through these urls.
Figure 8. Including the required files in the html document
We use the window.onload() function to set up some flags and create the SMDService(). The listing is shown in Figure 9. During the set up phase, we query the database for the currently available ontologies. While we wait for the query to return, an interval checker, setInterval („checkFlag()‟, 100) in the window.onload() function checks for the value of the variable „flag‟ in the function checkFlag(). checkFlag() is called every 100 ms until it is cleared. When the value of „flag‟ changes to 2, the initial database query has returned and the function buildWidgets() is called. buildWidgets() also queries the database and these queries must return before we can continue. When the value of the variable „flag‟ changes to 3, we are ready to continue and the interval checker is cleared. The two functions shown in Figure 9 must be included verbatim in the html file. Other javascript commands may be included in the window.onload() function as required by the application, such as calling other javascript functions which lay-out other parts of the html page or making database queries for previously selected values.
window.onload = function() { console = document.getElementById('console'); document.getElementById ('init').setAttribute ('flag', 1 ); doneYet = setInterval ('checkFlag()', 100 ); smdService = new SMDService(); } function checkFlag() { //query for ontology ids has completed if ( document.getElementById ('init').getAttribute ('flag') == 2 ) { buildWidgets(); } else if (document.getElementById ('init').getAttribute ('flag') == 3 ) { clearInterval (doneYet); } }
Figure 9. Javascript functions for initializing form The second part of the section of the html file defines each widget in JSON notation. A widget needs six pieces of data: title to be shown on the form (string) ontology id (database identifier, supplied by function call) ontology name (string)
term name (string) label (string) unique identifier (string or number )
Figure 10 shows the listing for a function called buildWidgets(), which is an example of how to create widgets. When defining a widget, the code must first get the database identifier for the ontology name. This is done by calling smdService.getOntologyId (ontologyName). The code below is creating an array of objects where each object will be one widget. Because javascript uses associative arrays to reference data fields and because it is not typed, care must be taken to use the identifiers exactly as defined below. The fields are title, ontId, ontName, termName, label, and uid. The values for title, label, and uid are user-specified. The label defines the context of the annotation to the page. The uid is a unique identifier, important when there are several widgets on one page. The uid can be a string or an integer; it just must be unique for each widget on the page. The termName allows the user to specify a root from which the ontology descends. If termName is the empty string, that is “” or „‟ or 0, the root of the ontology will be the root of the tree. If termName is a term name in this ontology, it will be the root. In this way, we can restrict the scope of the terms to the context of the annotation. For both the ontology name and the subroot term, we require an exact string match with the name and the term as defined in the ontology. In Appendix 3, we explain how you can check these names against our database. The buildWidgets() function, shown in Figure 10, creates three widgets: one for The MGED Ontology, one for Gene Ontology and one for NCBI_Taxonomy. The first widget is limited to search for terms which are children of the term BiologicalProperty . The second widget is limited to those terms that are descendents of biological_process in the Gene Ontology. The third widget displays all the terms in the NCBI Taxonomy ontology. Below the widget descriptions, the function loadWidgets() is called. Optionally, we have preselected the term growth in the Gene Ontology. The preselection feature can be used to display the term selected in a previous session or a default value.
Figure 10. Example: Building three data objects
The section
The last part of the html file is the body. In the body we define the
elements that hold a place for each widget on the page and define the five hidden inputs. The
elements for the widgets are named by the string id =„widget‟ + uid. Similarly the four hidden fields have ids in the form of: „ontology‟ + uid, „label‟ + uid, „termName‟ + uid, „accession‟ + uid. The fifth hidden input names the uid for this widget. In Figure 11, notice that the id of the form is „MainForm‟ as passed to SMDService(„MainForm‟).