view release on metacpan or  search on metacpan

README.ACEBROWSER  view on Meta::CPAN

  simple   An acedb database running on port 2005 of the 
	   local host

  moviedb  An example database of movies running on port 200008 
	   of stein.cshl.org

  default  An oldish snapshot of the C. elegans database running
	   on port 2005 of stein.cshl.org

To select among the data sources, append the symbolic name to the end
of the URL of the desired CGI script.  For example, to do a text
search on the "moviedb" database, fetch this URL:

  http://your.site/cgi-bin/ace/searches/text/moviedb

If no symbolic name is specified, the default database is assumed.
  http://your.site/cgi-bin/ace/searches/text 

is equivalent to

  http://your.site/cgi-bin/ace/searches/text/default

As described in EXTENDING ACEBROWSER, another way to select among
databases is to place the CGI script itself in a directory with the
same name as the database.  For example, if you have written a
specialized CGI script called screenplay that is designed to work with 
the "moviedb" database, you could place it in a subdirectory named
moviedb, and refer to it this way:

  http://your.site/cgi-bin/ace/moviedb/screenplay

The symbolic name can actually appear anywhere in the path, so this
would work as well:

  http://your.site/cgi-bin/ace/moviedb/custom/screenplay

THE CONFIGURATION FILES

The configuration files are located in the directory selected for
acebrowser configuration.  Their names are formed by appending ".pm"
to the symbolic name of the database.  For example, the configuration
file "simple.pm" corresponds to the database "simple".

Each of the configuration files is actually an executable Perl script.
As such it can use any Perl constructions you wish, including variable
interpolation.  The purpose of the configuration file is to set a
series of configuration variables, which by convention are all
uppercase.  For example, here is an excerpt from the default.pm
configuration file:

 $HOST = 'stein.cshl.org';
 $PORT = 2005;
 $USERNAME = '';
 $PASSWORD = '';

In addition to scalar variables, the configuration file is used to set 
arrays, hashes and specially-named functions.

If you are only interested in accessing a single database, it is
easiest to modify the default.pm configuration file.  To serve
multiple databases, just make a copy of default.pm and edit the copy.

If, for some reason, Acebrowser cannot find its configuration files,
it will generate an internal server error.  The location of the
configuration files directory is stored in the module
Ace::Browser::LocalSiteDefs, typically somewhere inside the
"site_perl" subdirectory of the Perl library directory (use "perl -V"
to see where that is).  You can find out where Acebrowser expects to
find its configuration files by running the following command:

  perl -MAce::Browser::LocalSiteDefs \
       -e 'print $Ace::Browser::LocalSiteDefs::SITE_DEFS,"\n"'

To change this value, either reinstall Aceperl or edit
LocalSiteDefs.pm manually.

EDITING THE CONFIGURATION FILE

The settings in the default.pm configuration file distributed with
AcePerl should work with little, if any modification.  The following
variables may need to be tweaked:

  $ROOT = '/cgi-bin/ace';

This is the root (top level) for all the Acebrowser CGI scripts.
Change this if necessary.

 $DOCROOT = '/ace';

This is the root (top level) for all of Acebrowser's static HTML files
and images.  You will need to change this if the static files are
installed somewhere else.

 $ICONS = "$DOCROOT/ico";

This is where Acebrowser expects to find its icons. This subdirectory
holds icons and other small static images.  Note how the
previously-defined $DOCROOT variable is used.  You will probably not
need to change this.

 $IMAGES = "$DOCROOT/images";

This is where Acebrowser expects to find its "images" subdirectory.
This directory contains images generated dynamically by the ACEDB
database.  It *must* be writable by the web server user, usually
"nobody".  When the AcePerl install script creates this directory, it
makes it world-writable by default.  You may prefer to make it owned
by the "nobody" user and/or group.

 $HOST = 'stein.cshl.org';

This is the name of the host where the desired acedb server can be
found.

 $PORT = 2005;

This is the network port on which the desired acedb server is
listening.  Network ports in the range 1024-65535 are assumed to
correspond to the newer socket-based sgifaceserver.  Ports in the
range 65536-4,294,967,296 are assumed to correspond to the older
RPC-based gifaceserver.

 $USERNAME = '';
 $PASSWORD = '';

For password-protected ACEDB databases, these variables contain the
username and password.

 $STYLESHEET = "$DOCROOT/stylesheets/aceperl.css";

This is the cascading stylesheet used to set the background color,
font, table colors, and so forth.  You probably don't need to change
this, but you might want to modify the stylesheet itself.

README.ACEBROWSER  view on Meta::CPAN

 @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'
   );

The @BASIC_OBJECTS array is used by the "basic" search script.  It
indicates the Acedb classes to offer to the user to search on, and the
labels to use for each class.  For example, the default configuration
will present the user with a radio button labeled "Confirmed Gene" for
use in searching the Acedb class "Locus".

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