Adding Data to a Widget (Example)

From WormBaseWiki
Revision as of 21:09, 13 June 2014 by KenanHabib (talk | contribs)
Jump to navigationJump to search

Introduction

A common form of feature request is add a piece of data to be displayed on a page.


Going through an issue example we are going to explain the work flow required to add some data to a widget.

Issue #2551 required showing the data under the "Former_designating_laboratory" field on the widget "Overview" of a "Gene class" (the Gene class "daf" for example).

Using the data flow graph

Widget Loading

we can see that data goes through 4 stages from the database to the UI - Rest, Conf, API and Template. Usually our work doesn't involve the Rest stage, but it sure does involve modifying the .conf (the configuration), .pm (the API) and .tt2 (the template) files.

Let's go back to our example. If you go to the "daf" page [1], you can view the database you are going to be working on by going to Tools -> Tree Display using the menu on the left side of the page. Our field "Former_designating_laboratory" has two data objects under it, a time "19 Mar 2014 14:41:19" and a link to the lab "DR". In this example we are only going to care about displaying the time on the "Overview" widget (if you can't see a widget you can show it by clicking on it from the side menu).

First Step:

Add a field in the configuration file. The wormbase.conf file, which you can find under the main website directory contains default configurations for the WormBase application. Now under the "overview" element of the "gene_class" section add the Former Designating Laboratory field "fields former_laboratory".

<gene_class> # <overview> name overview title Overview display report tooltip Gene class (eg Unc) overview. fields name fields other_names fields description fields laboratory fields former_laboratory # fields phenotypes fields remarks </overview>

Second Step:

We are going to add a subroutine to the API of the Gene class object in order to grab the data from the database. You can find the API file we need to fix in lib/WormBase/API/Object/, then find the Gene_class object.

We are going to add a subroutine and call it former_laboratory:

sub former_laboratory {

   my $self = shift;
   my $object    = $self->object;
   # Access the field Former_designating_laboratory
   my $former_lab_time = $object->Former_designating_laboratory;
    
    
   return   { description => 'Former_designating_laboratory', data =>  "$former_lab_time" || undef };
                      }

Return a hash that contains the description of the field and the former lab time. The value of the "data" key should be "undef" if there is no data in the "Former_designating_laboratory" field. If the "data" is "undef" the template won't show a "Former designating laboratory" field on the UI.

Third Step:

A template - with the file extension .tt2 - is responsible of view the data grabbed from the database on the the UI. Every widget in an object has its own separate template. So if you go to this directory root/templates/classes/gene_class/ which contains all the Gene class widgets you will find a template for the Overview widget with the name overview.tt2.

We are going to add a new WRAPPER for our field. The key parameter should match our subroutine name that we made in the API file - which was "former_laboratory" -.

WRAPPER $field_block title="$title"||'Former Designating Laboratory' key="former_laboratory";

    #Access the value of the "data" key returned from the former_laboratory subroutine
    fields.former_laboratory.data;

END;

You can check out how "$field_block" works from the page_elements.tt2 template. "$field_block" looks of the data returned from former_laboratory if "undef" or not. If it is "undef" - which means there is no data in the that field - it disables the element of the field, and it isn't going to show on the UI.

Forth Step:

There should be a test for any modification you do. In this example what we need to test is the API because we need to know if the "former_laboratory" subroutine in the Gene_classes API is grabbing the data properly from the database or not. There is a standard template "template.t" you can find in the directory t/api_tests/ , and you can use for your API tests.

So you are going to make a copy of the template - using the command "cp t/api_tests/template.t t/api_tests/gene_class.t" - and modify it. Let's call the new test file "gene_class.t". This is how the original template looks like this:

  1. !/usr/bin/env perl
  1. This is a unit test template for implementing tests that work
  2. with a running WormBase Website instance.
  3. Unit tests are called automagically, just adhere to the following:
  4. 1. the unit test is placed in the t/api_tests folder
  5. 2. the filename and package name coincide (sans suffix)
  6. 3. unit test names have the prefix "test_"
  7. Actual tests are implemented at the bottom of this file. Please see:
  8. 1. gene_class

{

   # Package name is the same as the filename (sans suffix, i.e. no .t ending)
   package template;
   # Limit the use of unsafe Perl constructs.
   use strict;
   # We use Test::More for all tests, so include that here.
   use Test::More;
   # This variable will hold a reference to a WormBase API object.
   my $api;
   # A setter method for passing on a WormBase API object from t/api.t to
   # the subs of this package.
   sub config {
       $api = $_[0];
   }
   
   # This is a test that checks whether former_laboratory attribute is correctly returned
   # related to #2551
   sub test_former_designating_laboratory {
       my $gene_class = $api->fetch({ class => 'Gene_class', name => 'daf' });
       can_ok('WormBase::API::Object::Gene_class', ('former_laboratory'));
       my $former_designating_laboratory = $gene_class->former_laboratory();
       # Please keep test names/descriptions all lower case.
       isnt($former_designating_laboratory->{'data'}, undef, 'data returned');

is($former_designating_laboratory->{'data'}->{'lab'}->{'id'}, 'DR', 'correct lab returned'); is($former_designating_laboratory->{'data'}{'time'}, '19 Mar 2014 14:41:19', 'correct time returned');

   }

}

1;

Make sure to read the instructions that are inside the template and to add the issue number in the comments.

Step Sex:

The only thing left for you now is to commit your code to git. If you have trouble doing that it's good to check out Development workflow - webdev.