Creating a simple custom view

Creating a dynamic page which shows a selection of data from one of the Ensembl databases is fairly straightforward.

Creating the page

1. Create a directory in your plugin to contain your custom code. If you want to put your code in the mirror plugin, it should be
   public-plugins/mirror/modules/EnsEMBL/Web
2. Decide on the Action for your new page. For example if you are basing your view around gene information, your URL might be
   <species>/Gene/MyViewName
3. Create a module which will add this URL to the available views. In our example, public-plugins/mirror/modules/EnsEMBL/Web/Configuration/Gene.pm will extend the current set of gene-based displays:

   package EnsEMBL::Web::Configuration::Gene;
   
   use strict;
   
   sub modify_tree {
     my $self = shift;
     
     $self->create_node('MyViewName', 'My Possibly Long Title for this View',
       [],
       { 'availability' => 'gene', 'concise' => 'My Short Title' }
     );
   }
   
   1;
   

   This will add your view to the bottom of the lefthand menu, and provides a framework to which HTML output components will be attached (see below).

   The 'concise' parameter is optional, and is a way of configuring an alternative, short name for your view that will appear in links (e.g. in the lefthand menu).

4. Create the components that will output the HTML. Let's say you want your page to include an image with a table underneath; you may find it easiest to create two separate components, EnsEMBL::Mirror::Component::Gene::MyViewImage and EnsEMBL::Mirror::Component::Gene::MyViewTable. Below is a Component template that can be used as the basis of any simple view:

   package EnsEMBL::Mirror::Component::Gene::MyViewImage;
   
   use strict;
   
   use base qw(EnsEMBL::Web::Component::Gene);
   
   sub _init {
     my $self = shift;
     $self->cacheable(1);
     $self->ajaxable(1);
     $self->configurable(0);
   }
   
   sub content {
     my $self = shift;
     
     ## The web 'object' is a wrapper around the Ensembl API object
     ## which a) makes the object extensible via plugins and
     ## b) usually includes methods that munge data into a web-friendly format
     my $object = $self->object;
   
     my $html;
   
     # Write your content-generating code here!
   
     return $html;
   }
   
   1;
   
   

   The easiest approach is to look at a page that has a similar display to the one you want, and modify a copy of that code.
5. Add the list of components to the Configuration::Gene module you created earlier, in the empty arrayref:

   $self->create_node('MyViewName', 'My Possibly Long Title for this View',
       [
         myviewimg     EnsEMBL::Mirror::Component::Gene::MyViewImage
         myviewtable   EnsEMBL::Mirror::Component::Gene::MyViewTable
       ],
       { 'availability' => 'gene', 'concise' => 'My Short Title' }
     );
   

6. Restart your server, and your completed page should now be accessible on your Ensembl installation!

Important note

You will note that the example in stage 3 has the package name EnsEMBL::Web::Configuration::Gene, while the one in stage 4 is EnsEMBL::Mirror::Component::Gene::MyViewImage.
When writing a plugin for an existing module, use the EnsEMBL::Web namespace.
In this situation the only functions you need to write are ones which replace existing functions, using the same function name (overwriting), or completely new functions (extending).
You do not even need the use base statement.
When writing a plugin for a new module, as in stage 4, use the EnsEMBL::Mirror namespace (where "Mirror" is whatever you've chosen as your plugin's namespace). These modules must be written in their entirety.

Custom data calls

If your new components need data that is not already available through the standard Object::Gene module, you can extend the module in the same way as Configuration and Component code:

package EnsEMBL::Web::Object::Gene;

use strict;

sub my_gene_info {
  my $self      = shift;
  my $api_obj   = $self->Obj; ## Bio::Ensembl::Gene object
  my $gene_info = {};

  ## Make API calls here!
  foreach my $trans (@{$api_obj->get_all_Transcripts()}) {
    ...
  }

  return $gene_info;
}


1;