Instructions for curators

Initial setup

• Setup a gifaceserver for the new acedb database
• Ensure that its disk is visable via NFS from the webace webserver
• Ensure that the webace webserver cache directory is visible by the gifaceserver
• Ask the webace administrator to add an entry for the database to the dbinfo file
• Copy the example webace_view.pl file into your acedb database wspec directory (this will override any global view functionality by initially turn it off).

Database specific customisation of webace by curators

• Definition of 'views' for graphical displays
• Definition of click 'modes' for graphical displays
• Auto addition of external URL links
• Addition of URL objects to database

1. Definition of 'views' for graphical displays of ace objects.

wspec/webace_view_'port'.pl
wspec/webace_view.pl
acelib/webace_view_'db'.pl
acelib/webace_view.pl

The extra file at the beginning of the search with the additional 'port' qualifier is to facilitate testing by curators. If you wish to experiment with the webace configuration files without affecting a live service, the best way is to run a separate www server on a different port (other than the default port 80). This should have a completely separate htdocs and cgi-bin tree (a duplicate copy of all cgi-bin, acelib files). By modifying the dbinfo file, other acedb servers can be connected to, however this is not essential if one just wishes to experiment with different view control settings. If one is the webace administrator of course it is easy to edit any webace_view*.pl files in acelib, however if one is a curator without write access to acelib it is only possible to edit files in wspec, which will be referred to by both CGI scripts on both webace www servers. To address this, 'display' first looks for wspec/webace_view_'port'.pl in its search list. Popular alternative ports are 8080 for example, in which case call this file wspec/webace_view_8080.pl

The file is included into the CGI script using 'eval' - if it does not compile then the only result is that neither views nor extra click modes are defined at all - the CGI scripts will continue to execute correctly. The syntax of the file can be with 'perl -c filename' to avoid these errors.

Although in both types of display the user interface is identical (a popup view menu), the way the view is defined is quite different. For GMAP displays, the actual data displayed corresponds to a named 'view' object previously defined within the acedb database in question. For FMAP displays, views are defined in the above file, by listing all the methods used in the database and flagged them as enabling or disabling for each view.

It is also possible to define a special view, abbreviated as 'auto', where the actual view depends on some set of rules, such as the object name or zoom factor. In the example file given this is used to implement semantic zooming for FMAP displays (only genes are displayed at low resolution, but more and more information is displayed as one zooms in) and for GMAP displays selection on the basis of object name.

An example of the elements of the file is given below.

1. view name/label definitions.

The structure of these is identical for FMAP and GMAP. An array (@) and a hash (%) are both required due to a limitation of CGI.pm (which may later be removed). The hash links the value ('def') with the label that will be displayed in the menu to the user ('Default view').

	@$rafmap_view=(
		       'def',
		       'chrctg1',
		       'chrctg2',
		       );
	%$rhfmap_view=(
		       'def','Default view',
		       'chrctg1','All clones',
		       'chrctg2','Selected clones',
		       );

The structure of these is different for FMAP and GMAP.

For GMAP, a set of view names are defined which map to view names already defined inside the relevant acedb. The hash defines the relationship between the values attached to each menu entry and the extra part of the acedb gifaceserver command that is required.

%gmap_acedb_viewcom=(
		     'def','',
		     'chr','-view webace_chr',
		     'chrctg1','-view webace_chrctg1',
		     'chrctg2','-view webace_chrctg2',
		     );

%fmap_col_index=(
		 'default',0,
		 'def',1,
		 'hom',2,
		 'gene',3,
		 'ggp',4,
		 );

%fmap_col=(
	   
	   # methods
	  
	   # real genes
	   'supported_CDS',
	   [1,1,1,1,1,],
	   'supported_mRNA',
	   [1,1,1,1,1,],

	   .......
	   
	   'Coords',
	   [2,2,2,2,2,],
	   'DNA Sequence',
	   [2,2,2,2,2,],
	   'Brief Identifications',
	   [2,2,2,2,2,],
	   'Text Features',
	   [1,1,1,1,1,],
	   );

Both FMAP and GMAP setups also allow the definition of %fmap_head and %fmap_key respectively, which will be printed as html at the top and bottom of the page respectively. Icons for each acedb defined colour can be found in /webace/I/colour.gif and can be used to build keys.

	%fmap_head=(
		    'def',1,
		    'chrctg1',1,
		    'chrctg2',1,
		    );
		    
	$fmap_head[1]='';
	
	%fmap_key=(
		   'def',1,
		   'chrctg1',1,
		   'chrctg2',1,
		   );
		   
# EDITABLE
	$fmap_key[1]=<<ENDOFTEXT;
Clone status colour key: 
<img src="../I/black.gif"> Archived/Submitted
<img src="../I/red.gif"> Finished
<img src="../I/lightred.gif"> Contiguous
<img src="../I/yellow.gif"> Assembly_start
<img src="../I/green.gif"> Shotgun_complete
<img src="../I/lightgray.gif"> Shotgun
<img src="../I/blue.gif"> Library_made
<img src="../I/lightblue.gif"> Fingerprinted
<img src="../I/white.gif"> DNA_made/Streaked<p>
ENDOFTEXT

2. Definition of click 'modes' for graphical displays.

The first is 'External Links'. When an acedb object is displayed as text, parts of it that can be parsed to build an External URL link using the definitions in 3 files, cgi-bin/acelib/standard_urls, wspec/markup.pl and cgi-bin/acelib/global_markup.pl (see below). The same definitions in standard_urls can be accessed via the values in @keys and $type returned from the subroutine definition below.

Set $use_external_link=1 to activate this mode. The string that is parsed is the information string displayed when the mouse is held over an object when in 'mouseover' mode. This is less information than is available to markup.pl, but should still be sufficient for many purposes. Careful naming of objects in acedb can be helpful, as shown in this case where object prefixes allow various types of sequence to be distinguished.

$type and @keys will be undefined by default. If no valid reference is returned, webace will return a page informing the user that there is no valid 'External Link' for this object.

# C. External Links

# EDITABLE
$use_external_link=0;

$external_link=sub{
    my($label)=@_;
    my($type,@keys);
    
# EDITABLE - define $keys[] and $type for different $label expressions
    if($label=~/^Sequence:em:(\w+)/i){
	$keys[0]=$1;
	$type="EMBLAC";
    }elsif($label=~/^Protein:sw:(\w+)/i){
	$keys[0]=$1;
	$type="SwissProtAC";
    }elsif($label=~/^Protein:tr:(\w+)/i){
	$keys[0]="tr:$1";
	$type="TremblAC";
    }elsif($label=~/^Protein:wp:(\w+)/i){
	$keys[0]="wp:$1";
	$type="WPAC";
    }
    
    return ($type,@keys);
};

Set $use_external_help=1 to activate this mode. Again the parsing is of the information string displayed when the mouse is held over an object when in 'mouseover' mode. In this case the URL returned is $ext merged with $stem, however it could easily be modified so each case defined a full URL to give a separate page for each entry. Here is the example html file, methods-help.html.

# D. External Help

# EDITABLE
$use_external_help=0;

$external_help=sub{
    my($label,$type)=@_;
    my($link,$stem,$ext);

# EDITABLE
    $stem="/webace/example-config/methods-help.html#";
    
# EDITABLE - define $ext for different $label expressions/$type combinations
    if($label=~/^Sequence:/i && $type=~/Map/i){
	$ext="mapsequence";
    }elsif($label=~/^PAC:/i){
	$ext="mappac";
    }elsif($label=~/^STS:/i){
	$ext="mapsts";
    }elsif($label=~/^Probe:/i){
	$ext="mapprobe";
    }elsif($label=~/^Sequence:(em|sp|wp)/i){
	$ext="sequence";
    }elsif($label=~/^Protein:/i){
	$ext="protein";
    }elsif($label=~/^Sequence:\w+\.(fgeneh|genscan)/i){
	$ext="gene_predictions";
    }
    
    if($ext){
	$link=$stem.$ext;
    }
    return $link;
};

3. Auto addition of external URL links to parts of an acedb object when viewed as text.

External URL definitions involve 3 files (see complete file list), cgi-bin/acelib/standard_urls, wspec/markup.pl and cgi-bin/acelib/global_markup.pl. markup.pl and global_markup.pl define rules to decide when to add URLs from standard_urls (completed with parameters extracted by the rules defined in the former). Unlike webace_view.pl, where a local file overrides a global file completely, here the rules in the first 2 files are adative, even if there are duplicates. To modify these files requires knowledge of the acedb object model, the models of the acedb database being curated and the representation syntax of acedb objects output by 'show -perl'. A simple example is:

In markup.pl

{'root'=> {'cl'=>'Sequence'},
 'keys' => sub {my ($node, $root) = @_;
		return ($node->{db},$node->{cl},$node->{va});
	    },
'urls'=>'display'
},

In standard_urls

display:view graphic:$main::baseURL/cgi-bin/$main::ndisplay?db=$keys[0]&class=$keys[1]&object=$keys[2]

4. Addition of URL objects to database

It is worth noting at this point that as well as true URL objects, various other tagname/text combinations are searched for and parsed into URL links by webace: text which appears to be an email address following a tag name 'Email' is marked up as a 'mailto:' link. Text which appears to be an http link following a tag name 'WWW_URL' is marked up as a'http' link (this is for historical support only - such entries should be changed to true URL objects).

Once you have a number of acedb databases served using webace (and perhaps know of a number of others elsewhere on the net you may want to want to consider adding crosslinks between your objects and objects in other databases. These links are made by creating URL objects which use the webace API to address an object. A level beyond this is that the exact object reference in the external acedb need not be known, as the URL object could also contain an acedb query (again formed using the webace API). Provided this query returns a single object, clicking on the URL object will jump directly to a webace display of the object pointed to. Details and examples on how to create crosslinks can be found here.