| Webace - AceDB on the web | [ Configure | Help ] |
Webace consists of 2 main CGI scripts, webace and display, the former handling the display of text information and the latter graphical images. The reason for there being 2 scripts is mainly historical - there is some duplication of code between them (although much that is common is in the module AceWWW.pm) and they certainly could be replaced by a single script, however this would probably result in slightly slower performance due to the longer perl compile time. The scripts respond to an API to return pages with either graphical or text representations of data extracted from the acedb database being queried and in turn contain hyperlinks to return other data via the same API.
The new functionality that has been added is to cache the html of objects as files stored in the htdocs/javascript directory of the webserver. This speeds up the second access of the object, but the main reason is to allow the expand/contract functionality of the standalone acedb programs to be implemented. By default, the initial html file displayed will show tags which are a list with more than 5 members as a hyperlink 'Expand'. Clicking here will return a page with this list expanded. This is implemented by storing the entire html in the cache, but with pairs of numerically labelled tags added around all lists embedded in the html as comment lines. By default all text between pairs of tags containing a list with more than 5 members are parsed out, before being passed to the browser by the CGI script. To implement the Expand functionality the API has been extended by adding the seme parameter, which can pass a list of the numerical labels and so control tags which should be ignored when the cache file is being parsed.
In a similar way, keysets (lists) of objects returned from acedb queries are also cached, the query being converted into a filename with extension 'keyset'.
The only other changes are that parsing rules have been added to markup URL objects, which are indicated by being surrounded by red '<>'. Links that have been added to external URLs via the global_markup.pl/markup.pl/standard_urls mechanism (see instructions for curators) are hyperlinked in italics. Data that has been entered (as opposed to text forming part of the model) is coloured red.
Although the principle has not changed, it is now managed in a substantially different way compared to the original webace. Before the 'gif' files were created by the standalone acedb program giface. Each clicking on an image sent the coordinates of the 'click' back to giface to generate a new image based on the intial state followed as many clicks as made by the user. The major problems were that (i) the giface program had to be restarted (loading the entire acedb database) for each user action; (ii) that the state might not be reinitialised for long periods (a long series of mouseclicks would result in a longer and longer response time as the effect of each click had to be redetermined each time) and (iii) that the action of identifying an object by clicking to highlight it was in itself costly, requiring waiting for a server response.
The new system addresses all these points: for (i), giface has been replaced by gifaceserver, which makes each query 'lightweight' since it only involves the invocation of an aceclient process. For (ii), clicks are mostly trapped as object references at the CGI level, so the gifaceserver is generally only sent a request for a defined state. For (iii), the information about the objects displayed on the gif is passed with the gif in the html page, to be displayed on the client side when the mouse is held over an object, by using either java or javascript. This eliminates the delay in obtaining this initial essential information. Both (ii) and (iii) result from gifaceserver not only writing out a gif file, but also a 'box' file, which lists all the object displayed in the gif with both their coordinates and information about them allowing a reference to be constructed to an acedb object. (iii) is possible by parsing this file and embedding its contents in the html page, either as a client side map with javascript mouseover function calls or as parameters to a java applet.
The functionality of the webace graphical displays is explained from the users prospective here as are details of how the alternative modes are selected. What follows here is a technical description of the implementation of the clickable gifs.
The system is complex since clickable gifs are implemented in 3 different ways, which all appear functionally similar to the user. These are (1) server side map; (2) client side map with javascript; (3) java applet. (3) was implemented mainly to support some of the javascript functionality on non javascript1.1 capable viewers (such as microsoft internet explorer 3) and as such bypasses the javascript system. (1) is used to support the display of gifs with large numbers of clickable items, when sending a list of their coordinates to the client would be prohibitively slow.
It is simplest for each user action to return new results in the same window, however this is not necessarily the most practical thing. Browser windows with graphics take a long time to redraw and so it is useful if the result of a click on a graphic appears in a second window. A simple model like this immediately lead to a propagation problem: window A contains a graphic, so clicks are designed to display in window B - however if window B later contains a graphic clicks on it should not display in window B but either A or C. Because in webace multiple alternative methods are used, it is important to appreciate is the problem of browser window control when javascript is not used: once a CGI script has been called, the browser is committed to display the results in the window that it was called from - form/submit and href operations can specify a target window for the results other than the current one, but only statically. This means that any selection in an html form that should change the target window needs to be evaluated on the client side before the submit operation. The only way to do this within the html itself is using javascript. Two approaches can be used: (a) to modify the target of a form on the page via a javascript routine called whenever a button/menu is selected and (b) for the submit to call a javascript routine directly, when passes the parameters on to the CGI having first evaluated the correct target window. (b) is used here, both to select target window and the appropriate CGI parameters, as discussed below.
The graphical display window is divided into two parts, separated by a horizontal rule. Below the rule is the current graphic. The selectors above the rule influence the new graphic that will be displayed if 'redraw' is clicked. The selectors below the rule either result in actions based on what is currently displayed (display of homology or dna) or affect the result of a click on the graphic itself. The 3 ways that clicks on the graphic are handled are as follows:
(1) server side map - used when 'mouseover' configuration setting of max objects
on a page is exceeded or when mouseover is 'off'.
No box information is embedded in the html page. Click coordinates are passed
back to the CGI as parameter which select a mode to scans the box file for a
match to an object. (If coordinates are passed on, these are no longer exactly
what the user clicked, but the top/left coordinate of the object to avoid
duplicate cache files). The click-action parameter is then interpreted - some
actions are processed directly; some cause the CGI to call itself for a second
time with different set of parameters.
(2) client side map with javascript - used when 'mouseover' enabled and
javascript selected.
Box information is embedded in the html page as a client side map with
javascript 'onmouseover' function calls (in fact it is actually passed
compressed, as a call to a javascript function which writes the client side map
inside the page on the client side - this reduces the size of the html file sent
greatly). Clicks call a javascript function embedded in the page (in fact all
the javascript functions are in a separate javascript script file which is
called by each page - to improve performance through caching) which interprets
the click-action parameter and then redirects to the appropriate CGI/URL/target window.
A special case is labelling, where a javascript routine actually creates the
content of an entire window and keeps track of a list of the entitities clicked
on within it - it is only clicking on 'Label' button within that page which
calls the CGI script 'label'.
(3) java applet - used when 'mouseover' enabled and java selected.
Box information is embedded in param tags of a java applet embedded in the html
page. The image is displayed by the applet itself and clicks are interpreted by
it. The click-action parameter is not displayed as the applet implements 2
alternative click actions directly: click results in a call to display the
object selected. shift-click highlights the object selected. At present no
other click-actions are supported.
Clearly, webace is not a clean way of doing things at all (corba and java developers will no doubt be horified if they have read this far) but it will do for the moment as it works! I fully expect it to be replaced by something much more elegant written by someone else at some time in the future, but I am not holding my breath!
15/3/98, webace@sanger.ac.uk