Using and customising z-menus

Information Software Ensembl architecture

Using and customising z-menus in Ensembl

What are z-menus?

In Ensembl, 'z-menus' refer to the pop up items that appear when features are clicked in the genome browser images. These items are used for navigation around the genome (zooming in, out and centering the view), and to display additional information regarding a specific feature. This page describes how to create, manage and otherwise manipulate the z-menus used in Ensembl.

There are potentially many uses for z-menus in Ensembl, but regardless of the intended application, the method by which new menus are created, or existing menus are customised is the same.

A word on asynchronicity

Ensuring that Ensembl is as fast loading and responsive as possible is a top priority for the system developers. As the overhead of requesting and processing the information required to populate the pop up z-menus in the various Ensembl views is relatively large, it is helpful to be able to such collect this information only as it is needed by the user. This processing happens in the background (ie: asynchronously) after the main page has loaded, as and when a feature in a view is clicked.

The method of creating and displaying information via z-menus automatically makes used of this asychronous behaviour.

Z-menu life cycle

1. A simple link

A z-menu starts life as link to a javascript function call, menu. When a new glyph is drawn to a DrawableContainer by either one of the GlyphSets in Bio::EnsEMBL::GlyphSet or the Sanger::Graphics::Renderer::imagemap, an entry is also made in the clickable image map for the resulting image which contains the information necessary to display the z-menu. Each glyph that requires a new z-menu be displayed should respond to a zmenu call, returning a new EnsEMBL::Web::Interface::ZMenu object. For example:

sub zmenu {
  ### Routing method
  my ($self, $gene, $transcript, $ajax) = @_; 
  if ($ajax) {
    return $self->ajax_zmenu($gene);
  } else {
    return $self->static_zmenu($gene, $transcript);
  }
}

sub ajax_zmenu {
  ### Creates a new z-menu object, and returns it.
  my ($self, $gene) = @_;
  my $zmenu = EnsEMBL::Web::Interface::ZMenu->new( (
                                     title => $gene->stable_id(),
                                     type  => 'ensembl_transcript',
                                     ident => $gene->stable_id(),
                               placeholder => 'yes'
                                      ) );
  return $zmenu;
}

sub static_zmenu {
   ### Code for synchronous menu display (slower)
   ...
}

This ZMenu object is then used by the imagemap renderer to generate the appropriate javascript link which will be used in the imagemap, via the EnsEMBL::Web::Interface::ZMenuCollection class. This class controls how the ZMenu objects are represented at the various different stages of their life cycle, and determins the protocol by which the server and browser will communicate when the ZMenu is populated asynchronously.

The image and image map are eventually sent to the browser, where the z-menu lies dormant as a javascript link. Each feature has its own unique link which, when clicked, will display the z-menu as it stands now (ie, empty), and start the background process of populating it with content.

2. An empty menu

When a user clicks on a feature in the Ensembl image, a javascript call is made (menu). This call immediately constructs and displays the menu as it stands. The javascript can be found in ajax_zmenu.js. By default, a placeholder z-menu will be displayed, which informs the user that the system is loading the menu content. As soon as the menu is displayed, an asynchronous call is made to populate_zmenu, to (unsurprisingly), populate the menu.

3. A populated menu

Once the asynchronous request is sent to the server from the feature click in Ensembl in the browser, at least one new object is created based on the type parameter of the original ZMenu. For example, above a new ZMenu placeholder object was created with a type of ensembl_transcript. As such, a new EnsEMBL::Web::Interface::ZMenu::ensembl_transcript is created. This object has the job of retrieving and processing the necessary information to populate the (currently empty) z-menu. The class should implement these functions in the populate method, which is called automatically on new ZMenu:: objects.

The ZMenu::ensembl_transcript will be passed in sufficient information to collate the necessary content. Once it is ready, a series of add calls can be made to populate the menu. For example:

add_text
add_link
add_html

Each method adds a new content row to the z-menu. Once the populate method is complete, the results are sent back to the browser, and the z-menu is populated via javascript. At this stage, the user should now be looking at the appropriate content.

4. A closed menu

Menus remain open once clicked and can be dragged around using the dark grey title bar, or minimised using the disclosure triangle. Clicking the 'X' will close the menu. Menus are not presently cached, so another click on the feature will reperform the asynchronous population.

Plugins and customisation

The z-menu procedure supports additional customisation through the Ensembl plug in system. When a menu is populated, the plugin directories are also searched for similarly named ZMenu:: objects. These objects are passed the same parameters as other objects via the populate call, and can add additional content to the menu via the add methdos above. Existing content which may have already been added by other plugins can also be removed with the remove_by_name function.

Non-asychronous behaviour

If necessary (for debugging, or on older browsers, for example), the asynchronous nature of the z-menus can be repressed. In place of returning an empty, placeholder ZMenu object from the glyph, a fully populated object can be returned. This populated menu will take longer to prepare, and take longer to download, but will be displayed in its completeness when a feature is clicked in EnsEMBL. For example:

sub zmenu {
  ### Routing method
  my ($self, $gene, $transcript, $ajax) = @_; 
  if ($ajax) {
    return $self->ajax_zmenu($gene);
  } else {
    return $self->static_zmenu($gene, $transcript);
  }
}

sub ajax_zmenu {
  ### Code for asynchronous menu display (faster)
  ...
}

sub static_zmenu {
  my ($self, $gene) = @_;
  my $zmenu = EnsEMBL::Web::Interface::ZMenu->new( (
                                     title => $gene->stable_id(),
                                     type  => 'ensembl_transcript',
                                     ident => $gene->stable_id(),
                               placeholder => 'no'
                                      ) );
  $zmenu->add_text('text1', 'ID: ' . $gene->stable_id() );
  $zmenu->add_link((name => 'link1', 
                    text => 'More: ' . $gene->stable_id(), 
                     url => 'http://www.ensembl.org' ) );
  return $zmenu;
}

.