Extending BioPortal's Rails UI

The BioPortal Web UI is primarily built using Ruby on Rails, which is an MVC framework built for the web. The views are plain HTML with the option to include Ruby in tags. We'll walk through a quick tutorial that will enable you to add your own sections of content on top of the existing Web UI. For our example, we'll add a section that will list tools that can be used to work with the ontologies in BioPortal. The Tools section will be a simple list that includes a tool's name, a web address, and a description. This list will be stored in a database and entries can be added, edited, and deleted.

For more guides on working with Rails, see http://guides.rubyonrails.org/v2.3.10.

This tutorial assumes that you have version .4 of the NCBO Virtual Appliance running in your virtualization environment.

  1. Log into Virtual Appliance with the root user
  2. Run cd /srv/ncbo/rails/BioPortal/current
  3. Run script/generate scaffold Tool name:string website:string description:string
  4. For more information on scaffolding, see the Ruby on Rails Guides
  5. You will see some output that indicates that Rails is creating files for you. Rails scaffolding will create a default set of views templates, a controller, and a model. It will also create a migration for the corresponding database table. Our example will have three columns, 'name', 'website', and 'content', all of which have string values.
  6. To actually create the database table, you'll have to run the migration using rake db:migrate RAILS_ENV=production
  7. Now that we have setup our new content area, we can restart the server to get the changes to show up. To do that, run ncborestart
  8. Visiting http://yourappliance/tools will show an empty default page with options to create a new tool. However, it doesn't look like BioPortal and it's missing all of the links to other parts of the site. We'll need to change the layout that the section is using.
  9. If we open the newly-created 'tools_controller.rb' file under app/controllers we can change the layout used by adding layout "ontology" directly under the 'class ToolsController < ApplicationController' line. If you refresh the page you can see it now shows the usual BioPortal layout. You can also read more about Rails layouts.

    • Note: You may need to run ncborestart again for these changes to take effect. To avoid this, you can run Passenger in the development environment, which will reload all controllers and templates on each request.
  10. The Tools section is fully functional at this point, you can add and remove tools using the generated code. The final piece is adding a link at the top of the page for your new section.
  11. The header links are contained in a sprite located here: 'public/images/layout/bp_nav_sprite.png'. This can be extended to include your own button using the original PSD file.
  12. The sprite contains two images per button, one for the "normal" state (white) and one for the "rollover/active" state (gray).
  13. Once you've added the two new images for the button in the sprite, export it as a png replacing the original 'bp_nav_sprite.png' file.
  14. You can add the HTML for the new button in the 'app/views/layouts/_topnav.html.erb' file after the section for 'Projects' (line 50) as follows:
  15. Edit the file 'public/stylesheets/layout/bioportal.css' and look for the section titled 'Topnav header image sprite'. Add the following CSS code to enable the new sprite (this assumes you created the two new images below the existing 'Browse' buttons):
  16. Refreshing the page should show your changes, including the link in the top navigation

Update 11/28/11: Clarified instructions and added a screenshot of the Tools section