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).

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).

Latest revision as of 18:31, 20 May 2013

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).

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.

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:

Rename the en.rb.sample file to en.rb

Modify the text in the file as you like

In the Rails ERB templates, we do translation lookups like this:

<%= t('home.intro') %>

Each dot reflects a nested element in the Ruby hash

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.

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.

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.

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.

To actually create the database table, you'll have to run the migration using rake db:migrate RAILS_ENV=production

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

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.

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.

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.

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'.

Refreshing the page should show your changes, including the link in the top navigation