This tutorial details how to implement a better support for feature synonyms, but can easily be extended to any type of synonyms supported by Chado. The tutorial aims to modify the standard Tripal Feature page so that:
- another column is shown, containing the list of known synonyms for that feature
- the standard search forms on "name" and "uniquename" are collapsed into a single search box that allows the user to filter on names, uniquenames, and synonyms in a single step
No programming skills are required, but some basic familiarity with the Tripal/Drupal system is.
The tutorial is made of the following steps:
- creating a materialized view listing all features synonyms (see http://tripal.info/node/135)
- updating the feature view integration page
- updating the feature search page to show the synonyms list
- updating the feature search page to allow a single search over feature name, uniquename, and synonyms
STEP 1 - Creating the materialized view
During this step we create a materialized view, named chado_feature_synonyms_list, that lists for each feature all of its synonyms. Go to the materialized view page (usually under <your_site>/admin/tripal/schema/mviews) and click on "Add materialized view". You will be required to name the materialized view, give its definition, and its population query. Please follow this link:
and paste on your site the code you find there. It is important that you name the view as chado_feature_synonyms_list, since the remaining parts of the tutorial reference this name.
Once your materialized view is created, it will need to be populated. Click on "populate" on the materialized view list. A message should inform you that the operation has been queued. There are a few ways to run it right away, but if you have shell access to your server the quickest one is through drush. The command will be:
drush trpjob-run administrator
or something similar (if your superuser name is not "administrator"). Once you have populated the materialized view, you'll be ready for the next step.
STEP 2 - Updating the feature view integration page
This step updates the existing "Chado feature" integration, and informs the system that the feature table can be linked to the materialized view we just created through the "feature_id" field. Follow these steps:
- go to the views integration page, usually at <your_site>/admin/tripal/views-integration
- find an integration called "Chado Feature". You can scroll the list, but it's easier if you put the word "feature" in the "chado table name" filter field
- once you found the integration, click on "edit", on the last column on the right
- if you see a warning telling that "You are editing a default views integration. To ensure your changes are used, change the priority to -10" do as it suggests and change the integration priority (any number equal or smaller than zero would work, actually)
- scroll down to the bottom of the page
- find and click on the "Show Joins & Relationships" link. It should open a hidden list
- scroll down again and find the NEW JOIN box
- fill the requested fields as follow:
- base column => feature_id
- the two central fields remains untouched (views_join and views_handler_relationship)
- uncheck "Relationship Only?"
- left table => chado_feature_synonyms_list
- left column => feature_id
- click on "Save & add Join". We are done for this step!
STEP 3 - Updating the feature view: show the synonyms list
In this step, we update the feature view so that the synonym list is shown. Follow these instructions:
- go to the view page list, usually under <your_site>/admin/structure/views
- find the "Feature User Search" (you can use the search mask) and click on Edit
- on the right, look for the "advanced" column (it is usually hidden by default, and you need to click on the "advanced" link)
- find the RELATIONSHIPS section, click Add. The "Add relashionship" overlay should appear
- in the overlay, search for "synonyms" and look for "Chado Feature: feature_id => Chado Feature Synonyms List". Check it
- click on "Apply (all displays)". The overlay will propose some options, but the standards will work. Click again on "Apply (all displays)". At this point we have linked the feature view with the materialized view and we can show the synonyms field
- on the left, look for the FIELDS section. Click "Add"
- search on the shown list, we are looking for "Chado Feature Synonyms List: Synonyms List". Add it and personalize as you prefer (you can change label, display order, sortability, ...)
- save the view (top right)
The list of synonyms should now be visible as another column in the feature table.
STEP 4 - Updating the feature view: allow a single search over name, uniquename, and synonyms
In this step, we modify the standard search fields to allow the user to perform a single search over feature name, uniquename, and synonyms. To do so we need to add another field to the view, but this time it must be hidden. Also, we need to have completed the previous steps. Follow these instructions:
- edit the feature view, as explained in the previous step of this tutorial
- add another field, this time the one named "Chado Feature Synonyms List: Uniquename And Synonyms List"
- check the " option for this field. In this way the field is hidden to the user.
- add another FILTER CRITERIA on the field we just added. Common choices for this filter would be:
- type: text field
- operator: contains any word
- filter exposed to the visitor
- filter operator NOT exposed to the visitor
- labeled "Name or alias contains" or something along this line
- save the view and test it. Any word or piece of word in the new filter should select a subset of existing features that match the entered value in name, uniquename, or alias
- remove the two existing filters on name and uniquename, since they are not needed anymore. To do so edit the feature view again, go to the filter section, and click on "And/Or, Rearrange" in the dropdown menu just on the right of FILTER CRITERIA (you need to click on the small triangle)
And we are done: our Tripal installation now supports Feature Synonyms!