Difference between revisions of "Adding Data to a Widget (Example)"

From WormBaseWiki
Jump to navigationJump to search
Line 10: Line 10:
 
If you go to the [http://staging.wormbase.org/resources/analysis/OMA#0312--10 OMA] page , 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.
 
If you go to the [http://staging.wormbase.org/resources/analysis/OMA#0312--10 OMA] page , 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.
  
==Modify configuration file==
+
== Formal Testing ==
Add the URL field "fields URL" to the overview element of the "analysis" section
+
 
 +
You have to do two tests when fixing any issue. One before fixing and another one after it's fixed. 
 +
 
 +
Here we focuse on API Tests, which check that an API module (the subroutine it has) successfully retrieves values from the database.
 +
 
 +
API Tests are located at <code>t/api_tests/</code> with the extension .t. '''A .t script usually test a single API module, such as one of the .pm file under lib/WormBase/API/Object/. It has a file name that matches the API module, which it tests.''' This convention helps with locating a test file, making it easier to add new test case.
 +
 
 +
* To add a test case, locate the test file as described above. Create one if you cannot find one by:
 +
** Copy the <code>template.t</code>, a sample test file, and name it according to which API module is being tested
 +
 
 +
* include a test case, which usually contains test for:
 +
** subroutine can be called on the API object
 +
** data is returned from the subroutine
 +
** data return is correct
  
(The wormbase.conf - contains default configurations for the fields inside widgets - is in the main website directory.)  
+
<nowiki>
 +
    # 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' });
  
<nowiki>
+
        can_ok('WormBase::API::Object::Gene_class', ('former_laboratory'));
<analysis>
 
  
<overview>
+
        my $former_designating_laboratory = $gene_class->former_laboratory();
name  overview
 
title  Overview
 
tooltip Concise overview of this analysis.
 
display report
 
fields name
 
fields description
 
fields title
 
fields based_on_wb_release
 
fields based_on_db_release
 
fields project
 
fields subproject
 
fields conducted_by
 
                        fields url
 
</overview>
 
  
      </analysis>
+
        # 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');
 +
    }
 
  </nowiki>
 
  </nowiki>
 +
 +
 +
'''Make sure to read the instructions that are inside the template and to add the issue number in the comments.'''
 +
 +
* Run a test script with
 +
<code>API_TESTS=testFileNameWithoutExtension perl t/api.t</code>
 +
 +
You have to make sure that all the tests you included failed, because you didn't actually fix anything.
  
 
== Add a subroutine to the API module ==
 
== Add a subroutine to the API module ==
Line 63: Line 77:
  
 
The value of the "data" key should be "undef" if there is no data in the field inspected, and this is why "|| undef" is added. This is important because if the "data" is "undef" the template won't show the field added on the UI
 
The value of the "data" key should be "undef" if there is no data in the field inspected, and this is why "|| undef" is added. This is important because if the "data" is "undef" the template won't show the field added on the UI
 +
 +
==Modify configuration file==
 +
Add the URL field "fields URL" to the overview element of the "analysis" section
 +
 +
(The wormbase.conf - contains default configurations for the fields inside widgets - is in the main website directory.)
 +
 +
<nowiki>
 +
<analysis>
 +
 +
<overview>
 +
name  overview
 +
title  Overview
 +
tooltip Concise overview of this analysis.
 +
display report
 +
fields name
 +
fields description
 +
fields title
 +
fields based_on_wb_release
 +
fields based_on_db_release
 +
fields project
 +
fields subproject
 +
fields conducted_by
 +
                        fields url
 +
</overview>
 +
 +
      </analysis>
 +
</nowiki>
  
 
== Edit template: for displaying data ==
 
== Edit template: for displaying data ==
Line 76: Line 117:
 
  </nowiki>
 
  </nowiki>
 
You can check out how "$field_block" works from the page_elements.tt2 template.
 
You can check out how "$field_block" works from the page_elements.tt2 template.
 
== Formal Testing ==
 
 
It's a good idea to include some test cases for your modification.
 
 
Here we focuse on API Tests, which check that an API module (the subroutine it has) successfully retrieves values from the database.
 
 
API Tests are located at <code>t/api_tests/</code> with the extension .t. '''A .t script usually test a single API module, such as one of the .pm file under lib/WormBase/API/Object/. It has a file name that matches the API module, which it tests.''' This convention helps with locating a test file, making it easier to add new test case.
 
 
* To add a test case, locate the test file as described above. Create one if you cannot find one by:
 
** Copy the <code>template.t</code>, a sample test file, and name it according to which API module is being tested
 
 
* include a test case, which usually contains test for:
 
** subroutine can be called on the API object
 
** data is returned from the subroutine
 
** data return is correct
 
 
<nowiki>
 
    # 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');
 
    }
 
</nowiki>
 
 
 
'''Make sure to read the instructions that are inside the template and to add the issue number in the comments.'''
 
 
* Run a test script with
 
<code>API_TESTS=testFileNameWithoutExtension perl t/api.t</code>
 
 
 
==Test and Commit Changes==
 
==Test and Commit Changes==
 
At last, test the web page on Dev site, and commit your code to git. If you have trouble doing that, it's good to check out [[Development workflow - webdev]].
 
At last, test the web page on Dev site, and commit your code to git. If you have trouble doing that, it's good to check out [[Development workflow - webdev]].

Revision as of 18:42, 18 June 2014

Introduction

A common form of feature request is adding some data to be displayed on a page.

Here is an example that illustrates work flow required to add some data to a widget.

Issue #2571 required showing the URL in the "URL" field on the "Overview" widget of an "Analysis" object (the analysis "OMA" 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.

If you go to the OMA page , 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.

Formal Testing

You have to do two tests when fixing any issue. One before fixing and another one after it's fixed.

Here we focuse on API Tests, which check that an API module (the subroutine it has) successfully retrieves values from the database.

API Tests are located at t/api_tests/ with the extension .t. A .t script usually test a single API module, such as one of the .pm file under lib/WormBase/API/Object/. It has a file name that matches the API module, which it tests. This convention helps with locating a test file, making it easier to add new test case.

  • To add a test case, locate the test file as described above. Create one if you cannot find one by:
    • Copy the template.t, a sample test file, and name it according to which API module is being tested
  • include a test case, which usually contains test for:
    • subroutine can be called on the API object
    • data is returned from the subroutine
    • data return is correct
    # 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');
    }
 


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

  • Run a test script with

API_TESTS=testFileNameWithoutExtension perl t/api.t

You have to make sure that all the tests you included failed, because you didn't actually fix anything.

Add a subroutine to the API module

Add a subroutine "url" to the API file of the Analysis object in order to grab the data from the database.

(The Analysis.pm - API file of the Gene class - is in the directory lib/WormBase/API/Object/.)

sub url {
    #An array reference "$self" to the array "@_" that contains the parameters passed to the subroutine
    my $self = @_;

    #Store the object parameter - which is the DB of the OMA analysis - in the variable "$object" 
    my $object = $self->object; 
    
    #Store the data in the "URL" field in the variable "$url" 
    my $url = $object->'URL';

    return {
        description => 'the url of the analysis',
        data        => "$former_lab_time" || undef,
    };
}
 

Always return a hash that has two keys; the "description" of the field added, and the "data" passed to the field. The value of the "data" can be a hash that contains multiple keys.

The value of the "data" key should be "undef" if there is no data in the field inspected, and this is why "|| undef" is added. This is important because if the "data" is "undef" the template won't show the field added on the UI

Modify configuration file

Add the URL field "fields URL" to the overview element of the "analysis" section

(The wormbase.conf - contains default configurations for the fields inside widgets - is in the main website directory.)

 
	<analysis>

		<overview>
			name   overview
			title  Overview
			tooltip Concise overview of this analysis.
			display report
			fields name
			fields description
			fields title
			fields based_on_wb_release
			fields based_on_db_release
			fields project
			fields subproject
			fields conducted_by
                        fields url
		</overview>

       </analysis>
 

Edit template: for displaying data

Add a WRAPPER to the overview widget - the widget we want to add the data to - template for the new 'URL' field. The key parameter should match the subroutine name that is in the API file.

(The overview.tt2 file is in the directory root/templates/classes/gene_class/)

WRAPPER $field_block title="URL" key="url";
      fields.url.data;
 END;

 

You can check out how "$field_block" works from the page_elements.tt2 template.

Test and Commit Changes

At last, test the web page on Dev site, and commit your code to git. If you have trouble doing that, it's good to check out Development workflow - webdev.