Modifying BioPortal Web UI

The BioPortal Web UI is primarily built using Ruby on Rails, which is an MVC framework built for the web. There are a variety of template types that are compatible with Rails, we use both ERB and HAML (and are trying to switch as we can to just HAML).

Getting the Code

Code is available on GitHub: https://github.com/ncbo/bioportal_web_ui

Translations

The BioPortal Web UI uses international localizations to handle much of the text that is seen, which means that you can change the text on many parts of your BioPortal install without actually modifying the template code. And since it's all in one file and that file isn't under version control, upgrading between versions should be a snap. In addition, this will allow us to support locale-based translations. While we don't have any translation yet -- and we don't have plans to create any -- we would gladly take contributions from the community.

There may be some areas of the site that haven't been split out into the translation file yet. If you have specific requests we can look at adding some more. This is another area where we would gladly take some community contribution.

Adding and Changing Text

The crux of the translation functionality can be found in a new folder: /config/locales

In here you will find a file, en.rb.sample, that contains sample code that you can use as a base. It's Ruby code so you can have access to variables that are assigned in the bioportal_config.rb file. To get started, do the following:

1. Rename the en.rb.sample file to en.rb
2. Modify the text in the file as you like
3. In the Rails ERB templates, we do translation lookups like this:
4. <%= t('home.intro') %>
5. Each dot reflects a nested element in the Ruby hash
6. To support things like the site and organization names, we've added some new options in the bioportal_config.rb file. If you're doing a new installation, use the provided bioportal_config.rb.sample file. Otherwise, see below.
7. Once you start the BioPortal Rails app (using Mongrel, Passenger, or your favorite app server), the translation file will be read in and used in the template files.
8. For more on Rails internationalization, see the i18n Guide

Tutorials

Adding a new section to BioPortal

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 or higher 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.
10. Note: You may need to run ncborestart again for these changes to take effect. To avoid this, you can run Passenger in the guide Apache.html#rails_env development environment, which will reload all controllers and templates on each request.
11. 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.
12. You can add the code for the new navigation button in the 'app/views/layouts/_topnav.html.erb' file after the main project logo (line 5) as follows:
    • <%=top_tab("Tools", "/tools", "tools")%>
    • This code is calling the top_tab method. The first argument is the name to use for the button. The second is the URL. The third is the corresponding controller (or controllers). The controller names are used to indicate when the link should appear 'active'.
13. Refreshing the page should show your changes, including the link in the top navigation