AceBrowser Enhancements - Enhanced tree display
The enhanced tree display is based on the normal AceBrowser tree display (tree), and can be used as a direct replacement for that display. The enhancement is support for cross links to external data sources. The display currently supports two kinds of markup: tag based markup and GFace style Pick_me_to_call markup.

Tag based markup
The $RULES data structure in AceMarkup.pm aims to emulate the type of markup offered by WebAce. It does this by mapping an ACEDB tag path (e.g. External_DB.AGR) to a small subroutine that generates a hyperlink to an external site.

GFace style markup
GFace uses a simple markup system in its tree display, which is based on having the database supply the actual markup description refered to by a Pick_me_to_call script name.

Basically the script name is used to look up the contents of a object in the database which describes the markup to use. This description is parsed and a URL generated. This URL is then used as the link for the script name.

The process and how to configure it is described in more detail in the GFace User's Guide, in the Configuration section.

Installation

• Download the two source files.
• Copy them into your AceBrowser directory (usually cgi-bin/ace).

Configuration
For GFace style markup see the GFace User's Guide, for information on constructing the markup description object, and then follow the basic configuration steps descriped below.

Basic configuration
Decide if you want to use the enhanced display instead of, or in conjunction with the normal tree display. If you want to use the enhanced display instead of the normal display (this tends to break in situ display of images):

• Rename tree to tree.dist, just in case you need it later.
• Copy, or rename, enh_tree to tree.

If you want to use the enhanced display and the normal display:

• Create a backup copy of the current state of SiteDefs.pm.
• Modify SiteDefs.pm:
  Add the enhanced tree display to the display mapper for your database.
  If you want to apply the change to all the databases then just modify the
  basic mapper (@BASIC_DISPLAYS). For example:
  

  %db_displays = (
      Paper => [
                { 'url'     => 'enh_tree',
                  'label'   => 'Enhanced Tree',
                  'icon'    => '/icons/text.gif' }
                ],
      Sequence => [
                { 'url'     => 'enh_tree',
                  'label'   => 'Enhanced Tree',
                  'icon'    => '/icons/text.gif' },
    
                { 'url'   => 'sequence',
                  'label' => 'Sequence Report',
                  'icon'  => '/icons/layout.gif' },
                   ],
                  );
            

  Modfify your database's URL mapper so that the display is used for the approprate classes. Again if you want to apply the cahnge to all the databases just modify the basic URL mapper (sub basic_mapper). For example:
  

  sub db_mapper {
     my ($display,$name,$class) = @_;
     my $n = escape($name);
     my $c = escape($class); 
  
     if ($class eq 'Paper' ||
         $class eq 'Sequence' ||
         $class eq 'Protein') {
         return ('enh_tree' => "name=$n&class=$c");
        } 
     # fall through
     return basic_mapper($display,$name,$class);
  }
        

• Modify AceSubs.pm Add display to list of CGI scripts (near the begining of the file). For example:

  # names of the CGI scripts that browse and search
  use constant TREE          => 'tree';
  use constant PIC           => 'pic';
  use constant SEARCH_SIMPLE => 'simple';
  use constant SEARCH_BROWSE => 'search';
  use constant SEARCH_GREP   => 'grep';
  use constant SEARCH_FIND   => 'query';
  use constant SEARCH_BLAST  => 'blast';
  # Enhanced tree.
  use constant ENH_TREE      => 'enh_tree';
  
  

• Add to list of exports (near the end of the file). For example:

  @EXPORT = qw(AceInit AceHeader AceError AceMissing 
               OpenDatabase TypeSelector Style Url 
               Object2URL HEADER FOOTER TREE PIC  
               NCBI ENH_TREE
              );
        

Tag based markup configuration
Create a 'rule' in the $RULES data structure for any pattern that you want to be recognised and marked up e.g.

'External_DB.MilletGenes' =>   
   sub {$MARKUP_SUB = 'webaceLink'; push @PARAM, 'millet'}
     

This rule specifies that whenever the CGI script enhanced tree is displaying an object that contains the tag path 'External_DB.MilletGenes', it should use the subroutine webaceLink() to create an external link. The code for webaceLink() should also be specified within AceMarkup.pm e.g.

sub webaceLink { 
   my ($db) = @_; 
   use constant LOCAL_URL => 
   'http://jiio5.jic.bbsrc.ac.uk:8000/cgi-bin/webace'; 
   return LOCAL_URL 
            ."?db=" 
            .$db 
            ."&class=" 
            .$CLASS 
            ."&obj=" 
            .$NAME; 
}

There are a few global variables that the curator will need to use to create external links:

$CLASS - This variable is initialised with the class of the ACEDB object that enh_tree is displaying.
$NAME - This variable is initialised with the name of the ACEDB object that enh_tree is displaying.
@PARAM - The curator can push additional parameters into this general purpose array. For instance, in the example above the subroutine webaceLink() needs to know which local database we are trying to link to so we push 'millet' onto @PARAM.

If you are thinking to yourself that this seems to be a bit of an untidy hack then you are probably right! However it is an extremely flexible solution in that the Perl subroutines can be as simple or as complex as required.