.

Building a Wizard

What is a wizard?

In Ensembl, a wizard is a collection of pages that guide a user through a collection of steps to perform a specific task. For example, wizards are used in registering new users. Wizards are useful when a task requires a large amount of information to be collected that may be daunting in a single page form, or that can be easily grouped together into logical chunks. Collecting and processing biological information often requires both, and so Ensembl includes a collection of modules to facilitate the building of wizards.

Wizard comprise nodes

Wizards are made up of a number of different steps, linked together to guide the user through a specific task. In Ensembl each step of this process is called a node. Nodes are linked together to form a wizard (see The wizard response chain). In general, a single node would perform one of three functions:

• Display a form: for data collection and verification
• Display a message: rendering a status message, response or other information to the browser in standard HTML.
• Perform a background task: typically database access of some kind. Once the background task is complete, the node redirects the user to the next appropriate step in the process, and typically displays no information itself.

The wizard response chain

Nodes are arranged into a response chain, which takes the form of a directional acyclic graph. The edges of the graph indicate how a user is guided through the wizard. For example, a wizard designed to add new information to a database may have the following response chain.

        +-html node------+
        |  Instructions  |  
        +----------------+
                ↓
        +-form node------+
        |  Data entry    |  
        +----------------+
                ↓
        +-task node------+
        |  Database add  |  
        +----------------+
                ↓
        +-html node------+
        |  Response      |  
        +----------------+
    

In this wizard, a user is first presented with a set of instructions, and (typically) a 'Next' button. On clicking the button, they are taken to a form where they can enter information to insert into the database, a 'Back' button to return to the instructions, and a 'Save' button to proceed to the next stage: the task node. This node attempts to add the information from the data entry node into the database and records the response (or any other information from the database). It then forwards the user to the final response node, which displays the success (or otherwise) of the database access.

Creating a Wizard in Ensembl

Wizards in Ensembl are all subclasses of the EnsEMBL::Web::Wizard class. Typically, the Wizard's are named after the data types which are often seen elsewhere in Ensembl: EnsEMBL::Web::Wizard::Chromosome, EnsEMBL::Web::Feature, EnsEMBL::Web::Wizard::User.

Wizard setup

Each Wizard module contains all the information required for all possible steps in a wizard guide. Each step (ie, each node) has a name associated with it, and are defined in the %all_nodes hash. In addition to all nodes being defined, all form elements appearing within all nodes are also defined, in the %form_fields. All possible messages are also stored in the Wizard module, in the %messages hash.

When a new wizard object is created (see Creating a wizard object), an _init method is called on instantiation. Setting up the %all_nodes, %form_fields and %messages hashes (along with some other configuration options) should be done here. For example, our database addition wizard (for storing names and organisations) could be configured like this:


• Form field elements:

      my %form_fields = (
        'user_id'   => {
            'type'=>'Integer',
            'label'=>'',
        },
        'email'     => {
            'type'=>'Email',
            'label'=>'Email address',
            'required'=>'yes',
        },
        'password'  => {
            'type'=>'Password',
            'label'=>'New Password',
            'required'=>'yes',
        },
        'confirm_password'  => {
            'type'=>'Password',
            'label'=>'Confirm Password',
            'required'=>'yes',
        },
        'name'      => {
            'type'=>'String',
            'label'=>'Your Name',
            'required'=>'yes',
        },
        'org'       => {
            'type'=>'String',
            'label'=>'Organisation',
        }
     );
     

• Node definitions:

     my %all_nodes = (
        'instructions'   => {'title' => 'Add new name wizard',
                          'page' => 1, 
        },
        'data_entry'     => {
                        'form' => 1,
                        'title' => 'Please enter your details',
                        'input_fields'  => [qw(name password email org)],
        },
        'database'      => {},
        'response'   => {'title' => 'Database response',
                          'page' => 1,
        },
     );
     

• Messages:

     my %message = (
       'success' => "Thank you. Your details were added to the database",
       'failure' => 'Sorry. Your request failed.',
     );
     

Once the new Wizard node definitions are in place, the actual logic for each node should to be added.


Adding node logic

Each node definition is assigned a name, as the key of the all_nodes hash. In this example, the names would be instructions, data_entry, database and response. A method call is made when each node is processed, depending on the node's name. In this example, each node should also have a similarly named method included in the Wizard module.

   package EnsEMBL::Web::Wizard:DatabaseAdd.pm;
   
   sub _init {
      ## node definitions and initialisation
      ...
   }
  
   sub instructions {
     ## empty method - output is determined by 
     ## the component
   }

   sub data_entry {
     my ($self, $object) = @_;
     my $wizard = $self->{wizard};
     my $node = 'enter_details';

     my $form = EnsEMBL::Web::Form->new($node, "/$species/$script", 'post' );

     $wizard->add_title($node, $form, $object);
     $wizard->add_widgets($node, $form, $object);
     $wizard->add_buttons($node, $form, $object);
     return $form;
   }

   sub database {
     ## database connectivity
     ...
   }

   sub response {
     ## empty method - output is determined by 
     ## the component
   } 

   1;
   

See the Wizard API documentation for more information.

Creating a wizard object

Once the node definitions and form elements are in place in the Wizard module, the wizard should be configured to be displayed for particular requests. This is done in the corresponding Configuration module. For example:

   sub add {
     my $self   = shift;
     my $object = $self->{'object'};

     my $wizard = EnsEMBL::Web::Wizard::User->new($object);

     $wizard->add_nodes([qw(introduction data_entry database response)]);
     $wizard->default_node('introduction');

     $wizard->add_outgoing_edges([
          ['introduction' => 'data_entry'],
          ['data_entry' => 'database'],
          ['database' => 'response'],
     ]);

     $self->add_wizard($wizard);
     $self->wizard_panel('Add data');
   }
   

Rendering wizard content

As with other pages and panels in Ensembl, a Wizard's HTML output is determined by the appropriate Component module. For example, the EnsEMBL::Web::Component::User component is responsible for displaying information relating to the EnsEMBL::Web::Wizard::User wizard.

Standard HTML nodes do not perform any operations when they are displayed (reflected by an empty node method call in the Wizard (see sub introduction and sub response above). Their companion Component methods determine how these nodes are displayed:

   sub introduction {
     my ($panel, $object) = @_;
     my $html = "..." 
     ## Setup HTML for output
     ...
     $panel->print($html);
     return 1;
   }
   

Form nodes can configure additional HTML, but must also setup the appropriate form for output:

   sub data_entry {
     my ($panel, $object) = @_;
     my $html = "..." 
     ## Setup HTML for output
     ...
     $html .= $panel->form('data_entry')->render();
     $panel->print($html);
     return 1;
   }
   

Node definitions

Each node definition contains a number of key value pairs used to configure the node's behaviour and display. Commonly used keys are described below:

page	Sets the node to be an HTML page.
form	Sets the node to be include a form.
title	Determines the title of the form for use in Component rendering.
input_fields	An array of field element names for inclusion in the node's form
pass_fields	An array of field element names to be passed along to the next node.
show_fields	An array of field element names for display. These have usually been passed from the previous node.
button	The label of the button used to arrive at the node. This is displayed on the previous node's page.

---

GermOnline

• GermOnline home
• Search genes
• BioMart data mining
• Export data
• Download data

GermOnline based on Ensembl release 50 - Jul 2008