README-PLUGINS

These are notes on the plug-in architecture.

Plug-ins are .pm files stored in the gbrowse.conf/plugins directory.
There are three types of plugins:

      1) dumpers
	 These plugins receive the genomic segment object and generate
	 a dump -- the output can be text, html or some other
	 specialized format. Example: GAME dumper.

      2) finders
	 These plugins accept input from the user and return a list of
	 genomic regions.  The main browser displays the found regions
	 and allows the user to select among them. Example: BLAST search.

      3) annotators
	 These plugins receive the genomic segment object and
	 return a list of features which are overlayed on top 
	 of the detailed view.  Example: restriction site annotator.
	
All plug-ins inherit from Bio::Graphics::Browser::Plugin.  It defines
reasonable defaults for each of the methods.  Specific behavior is
then implemented by selectively overriding certain methods.

CONFIGURATION ACCESS METHODS

The following methods can be called to retrieve data about the
environment in which the plugin is running.  These methods are also
used by gbrowse to change the plugin state.  See the section at the
end of this document for more details.

$config = $self->configuration

  Retrieve the persistent configuration for this plugin.  The
  configuration is a hashref.  Due to cookie limitations, the values
  of the hashref must be scalars or array references.

$database = $self->database

  Get a copy of the Bio::DB::GFF or Gadfly database handle.

$b_config = $self->browser_config

  Get a copy of the Bio::Graphics::Browser object.  This object
  provides access to values in the stored in the gbrowse configuration
  files.

$plugin->browser_config($bio_graphics_browser)
  Get a copy of the Bio::Graphics::Browser
  object.  This object provides access to values in the
  stored in the gbrowse configuration files.  

$plugin->config_path($path)
  Get the gbrowse configuration directory path.  You can use
  this within a plugin method to retrieve the path to any
  configuration files the plugin might depend on.

METHODS COMMON TO ALL PLUGINS - YOU SHOULD OVERRIDE THESE

All plugins will need to override these methods.

$string = $plugin->name();
  Return a short name for the plugin.  This will be displayed to
  the user in a menu using one of the following forms:

      Dump <name>
      Find <name>
      Annotate <name>

$string = $plugin->description();
  Return a longer description for the plugin.  May contain HTML tags.
  Invoked in response to the "About..." button.

$string = $plugin->type();
  Return one of "dumper", "finder", "annotator".  The default is
  "dumper".

$settings = $plugin->config_defaults();
  Generate a hashref containing settings.  This will be stored
  between sessions in a cookie.  Because of limited serialization
  and cookie space restraints, the values of the settings hash
  must be scalars or array refs.



METHODS TO BE IMPLEMENTED IN DUMPERS

All dumper plugins will need to override these methods.

$plugin->mime_type;

Returns the MIME type for documents generated by this plugin, for
example "text/html".  Plugins that generate more than one format may
select the mime type dynamically based on their current configuration.
The default MIME type is "text/plain."

$plugin->dump($segment);
  Dump out the data (dumpers only).

See the FastaDumper.pm and GFFDumper.pm modules for examples of how
this works.



METHODS TO BE IMPLEMENTED IN FINDERS

All finder plugins will need to override these methods.

$segments = $plugin->find($segment); 
  Do a find (finders only) and return an arrayref of triplets of form
  [ref,start,stop].  If further configuration is needed return undef
  -- gbrowse will invoke configure_form() and try again.  If
  nothing is found, return empty list.

  NOTE: You can ignore the segment and do the find on the whole 
  database if that's more appropriate.  If you need auxiliary files
  like BLAST files, you can store that information in the .conf
  file or handle your own conf files.

$segments = $plugin->auto_find($search_string);
  If a finder plugin has a auto_find() method defined, then in the
  event that the user types a search string into the gbrowse
  search box that isn't recognized by the default search mechanism, 
  then the search string will be passed to the auto_find() method.

See the OligoFinder.pm example module for how this works.



METHODS TO BE IMPLEMENTED IN ANNOTATORS

All annotator plugins will need to override these methods.

$feature_file = $plugin->annotate($segment)
  Annotate the segment and return a Bio::Graphics::FeatureFile
  object containing the annotations.  This is then plugged into
  the detailed view and track configurator.

See the RestrictionAnnotator.pm module for how this works.
	


METHODS WITH REASONABLE DEFAULTS THAT YOU MIGHT WANT TO OVERRIDE

$plugin->database($database)
  Get/set a copy of the Bio::DB::GFF or Gadfly database handle.

$plugin->browser_config($bio_graphics_browser)
  Get or set a copy of the Bio::Graphics::Browser
  object.  This object provides access to values in the
  stored in the gbrowse configuration files.  

  To fetch the current Bio::Graphics::Browser object,
  invoke browser_config from within a plugin method
  like this:
    
      $browser = $self->browser_config();

$plugin->config_path($path)
  Get/set the gbrowse configuration directory path.  You can use
  this within a plugin method to retrieve the path to any
  configuration files the plugin might depend on.

$plugin->page_settings($settings)
  Get/set the GBrowse page settings. This is a big hash whose
  structure is described in the source code for the gbrowse
  executable.

$plugin->init
  This is a chance to do other configuration.  It is called
  *after* calling database(), browser_config(), config_path() and
  page_settings() to set the like-named instance variables.  The
  default init() method does nothing.

$plugin->configuration($current_settings);
  Get/set current settings.  This will be called before 
  configure_form().  The settings are a hash reference
  containing anything you want.

$plugin->configure_form();
  Generate an HTML form that prompts user to set/change current
  configuration.  The fragment will automatically be surrounded by 
  <FORM> and </FORM> tags.

  All form fields must be preceded with the plug-in's name,
  in the format "<name>.<field>" (a dot separates the two).

  The method is expected to return a string containing the
  HTML that produces the form.
  
$plugin->reconfigure
  This gives the plugin a chance to reconfigure itself
  after its form is submitted.  It should call the CGI param()
  method to get its arguments. This will only be called
  if param() returns at least one parameter name that begins
  with the plugin's name.