view release on metacpan or  search on metacpan

README.ACEBROWSER  view on Meta::CPAN

This array indicates the location of the "images" subdirectory.  The
first element of the array is the location of the directory as a URL,
and the second element is the location of the directory as a physical
path on the file system.  This array is ignored when running under
modperl/Apache::Registry; modperl uses $IMAGES to look up the
corresponding physical path.

 @SEARCHES   = (
	       basic => {
			name   => 'Basic Search',
			url    =>"$ROOT/searches/basic",
		       },
	       text => {
			name   => 'Text Search',
			url    =>"$ROOT/searches/text",
		       },
	       browser => {
			   name => 'Class Browser',
			   url  => "$ROOT/searches/browser",
			  },
	       query => {
			 name => 'Acedb Query',
			 url  => "$ROOT/searches/query",
			 },
	       );
 $SEARCH_ICON = "$ICONS/unknown.gif";

The @SEARCHES array sets the searches made available to users.  The
first element in each pair is the symbolic name for the search.  The
second element is a hash reference containing the keys "name" and
"url".  The name is the bit of human readable text printed in the
list of searches located at the top of the AceBrowser page.  The url
is the URL of the script that performs the search.

The $SEARCH_ICON variable selects an icon to use for the search
button.


 @HOME      = (
	      $DOCROOT => 'Home Page'
	     );


Select the URL and label for the "home" link appearing on the bottom
of each Acebrowser-generated page.  By default, the home will point to 
"/ace" directory on the local machine.

 %DISPLAYS = (	
	     tree => {
		      'url'     => "generic/tree",
		      'label'   => 'Tree Display',
		      'icon'    => '/ico/text.gif' },
	     pic => {
		     'url'     => "generic/pic",
		     'label'   => 'Graphic Display',    
		     'icon'    => '/ico/image2.gif' },
	    );

As described in EXTENDING ACEBROWSER, the %DISPLAYS hash declares a
set of pages, or "displays", to be used for displaying certain Ace
object types.

 %CLASSES = (	
	     Default => [ qw/tree pic/ ],
	   );

As described in EXTENDING ACEBROWSER, the %CLASSES hash describes how
Acedb classes correspond to displays.

 sub URL_MAPPER {
   my ($display,$name,$class) = @_;
   ...
 }

As described in EXTENDING ACEBROWSER, the URL_MAPPER subroutine allows
you to tinker with the way in which Acedb classes are turned into
links.

 $BANNER = <<END;
 <center><span class=banner><font size=+3>Default Database</font></span></center><p>
 END

The $BANNER variable contains HTML text that will be displayed at the
top of each generated page.  You will probably want to change this.

 $FOOTER = '';

The $FOOTER variable contains HTML text that is displayed at the
bottom of each generated page.  You will probably want to change this.

 $PRINT_PRIVACY_STATEMENT = 1;

If this variable is set to true, then AceBrowser will generate a link
in the footer that displays a privacy statement explaining
AceBrowser's use of cookies.

 @FEEDBACK_RECIPIENTS = (
			[ " $ENV{SERVER_ADMIN}", 'general complaints and suggestions', 1 ]
 );

This array contains a list of recipient e-mail addresses for the
"feedback" page.  Each recipient is an array reference containing
least two elements, the e-mail address and a comment.  A third,
optional, element, if true, indicates that this recipient should be
selected by default.  The default is the webmaster's e-mail address.
Comment out the entire section of you do not want the feedback link to 
appear.

 # configuration for the "basic" search script
 @BASIC_OBJECTS = 
   ('Any'          =>   '<i>Anything</i>',
    'Locus'        =>   'Confirmed Gene',
    'Predicted_gene'    =>   'Predicted Gene',
    'Sequence'     =>   'Sequence (any)',
    'Genome_sequence', => 'Sequence (genomic)',
    'Author'       =>    'Author',
    'Genetic_map'  => 'Genetic Map',
    'Sequence_map' => 'Sequence Map',
    'Strain'       =>  'Worm Strain',
    'Clone'        => 'Clone'
   );

README.ACEBROWSER  view on Meta::CPAN

USING ACEBROWSER WITH MOD-PERL

Acebrowser is designed to work well with modperl
(http://perl.apache.org).  In fact, using it with a modperl-enabled
Apache server will increase its performance dramatically.

To use Acebrowser with modperl, install the CGI scripts into a
directory that is under the control of Apache::Registry.  The
<Location> section in httpd.conf should look like this:

 Alias /acedb/ /usr/local/apache/cgi-bin/ace/

 <Location /acedb>
   SetHandler Perl-script
   PerlHandler Apache::Registry
   PerlSendHeader On
   Options +ExecCGI +Indexes
 </Location>

Change the paths as appropriate.  The Acebrowser scripts located in
/usr/local/apache/cgi-bin/ace can now be accessed under modperl at the 
URL /acedb, as in:

  http://your.site/acedb/searches/text

When running under modperl, you can force all the CGI scripts in a
directory to use a particular configuration file by defining the
AceBrowserConf configuration variable .  For example, to create a
virtual directory named /movies and force all the scripts within it to
use the moviedb configuration file:

 Alias /movies/ /usr/local/apache/cgi-bin/ace/

 <Location /movies>
   SetHandler Perl-script
   PerlHandler Apache::Registry
   PerlSendHeader On
   Options +ExecCGI +Indexes
   PerlSetVar AceBrowserConf /usr/local/apache/conf/acebrowser/moviedb.pm
 </Location>

Be sure also to edit moviedb.pm $ROOT variable to indicate the correct
location of scripts in URL space:

 $ROOT = '/movies';


EXTENDING ACEBROWSER

Acedb is fundamentally object based.  In addition to having a name,
each object has a class, such as "Sequence".  Acebrowser takes
advantage of this object structure by allowing you to assign one or
more displays to a class.  Each display is a CGI script that fetches
the desired object from the database, formats it, and displays it as
HTML or an image.

Whenever Acebrowser is called upon to display an object, it consults
the configuration file to determine what displays are registered for
the object, and then presents a row of display names across the top of
the window.  In Acebrowser jargon, this line of displays is called the
"type selector."  The user can change the display to use by selecting
the corresponding link.

Three generic displays, which will work with all databases, come with
Acebrowser:

  tree  an HTML representation of the Acedb object which
	presents the object in the form of a collapsible outline.

  xml   an XML representation of the Acedb object

  pic   a clickable GIF image, as returned from gifaceserver.


Writing New Display Scripts
---------------------------

To register a new display script with the system, you will need to do
three things:

1. Write the script.  The easiest way to do this is to take the
moviedb "misc/movie" script, copy it, and go from there. 

The script will be invoked with the CGI parameters "name" and "class",
corresponding to the name and class of the Acedb object to display.
For example, if the script is located in /cgi-bin/ace/newscript, it
will be invoked as:

  http://your.site/cgi-bin/ace/newscript?name=foo;class=bar

2. Register the display with the %DISPLAYS hash in the configuration
file, by adding a hash entry like the following:

	     newdisplay => {
		 url   => "/cgi-bin/ace/newscript",
		 label => 'New Display',
		 icon  => '/ico/layout.gif',
		 },

The hash key, in this case "newdisplay", is a symbolic name for the
display.  It can correspond to the acual name of the CGI script, or
not.  The hash value is itself an anonymous hash containing the
required keys "url" and "label", and the optional key "icon".  "url"
gives the path to the script that will display, and "label" gives a
human readable label for the link that Acebrowser puts in the type
selector. The "icon" key, if present, will display the indicated icon
in the type selector.

3. Bind this display to the class (or classes) for which this display
is valid, by adding an entry to the %CLASSES array.  For example:

	  NewObject    => ['newdisplay'],

This indicates that whenever Acebrowser is called upon to display an
object of type "NewObject", it will display the object using the CGI
script designated by the "newdisplay" display.  If you have several
displays that are appropriate for a class, you can bind them all to
the class in the following fashion:

          NewObject => ['newdisplay','newerdisplay','newestdisplay'],

When creating a link for an Acedb object, Acebrowser will choose the
first display in the array.  When the object is displayed, all three
of the alternative displays will appear in the type selector.

More information on writing display scripts can be found in the
documentation for Ace::Browser::AceSubs.  From the command line, run:

  perldoc Ace::Browser::AceSubs

Writing New Searches
--------------------

To create a new search, 

1. Write a script following the model of one of the existing scripts.
Ace::Browser::SearchSubs exports subroutines that are useful in
managing the multiple pages of results produced by most search
scripts.

2. Register the new script in the @SEARCHES array.  Provide an
explanatory name for the search script, and a pointer to its URL.

More information on writing search scripts can be found in the
documentation for Ace::Browser::SearchSubs.  From the command line, run:

  perldoc Ace::Browser::SearchSubs

FOR HELP

Please write to the Acedb newsgroup, acedb@sanger.ac.uk for help or to
report possible bugs.  If you get really stuck, write to the author,
lstein@cshl.org.

Lincoln D. Stein
September 24, 2001