Difference between revisions of "Umlaut Local Configuration Architecture"

Revision as of 14:37, 11 June 2009

Principles/Goals:

1. Ideally you will not need to edit the common Umlaut codebase to make purely local customizations. All local customizations should occur via various types of configuration options, with the common Umlaut codebase being untouched - except with changes of wider applicability you submit back to the common codebase.
2. This means any code or config for local customization will ideally be kept clearly distinct from the common codebase.
3. If you like, you should be able to keep any of your local code or config files in your own local SVN or CVS repository, while at the same time getting shared codebase Umlaut code from the central Umlaut repository, combined together in a working Umlaut installation. (You might or might not want your production Umlaut to be an SVN working copy, but if you are a developer you will certainly want your development copy to be!)

To accomplish this required doing things a tiny bit different than standard Rails.

We realized after the fact that the Rails Engines plugin might be a great solution to those Goals, requiring less that's 'not the Rails way', and may explore refactoring Umlaut to be an Engines plug-in. But hasn't happened yet.

Where in a normal Rails app you would customize various files in the config directory, in Umlaut the files in the config directly have common Umlaut configuration necessary for any Umlaut environment, but your local config is instead in files in config/umlaut_config. There are files used in umlaut_config that look very much like the standard Rails config files (eg database.yml, environment.rb), and also some Umlaut specific ones (eg services.yml, institutions.yml).

Directory Locations For Local Content

umlaut_config is just one of Umlaut's locations where local and localized code, config, and data lives:

• $Umlaut/config/umlaut_config: local configuration
• $Umlaut/public/local : Local graphics and other resources that can be served directly by the web server.
• $Umlaut/app/views/layouts/local : Local layouts (Used to put local banner, footer, stylesheets etc. on your pages)
• $Umlaut/app/views/local : Used to store any local Rails 'views', entirely customized page layouts of Umlaut functionality for local needs.

Other locations that are NOT yet used, but would be reasonable extensions of this architecture in the future:

• $Umlaut/app/controllers/local
• $Umlaut/app/models/local

Rake Tasks to Aid in Management of Local Locations

Integrating somewhat elegantly with Rails means that your local content is spread accross several different directories. Umlaut provides some rake tasks and a generator to help you deal with them.

Generation of local files

There is a a generator to create all these locations, and seed them with some sample data - since we want to make it easy to control them in your own SVN, you don't get even these local directory locations from the Umlaut svn.

You may already have run the generator to create these files from the [Umlaut Setup] step, but if not, change into $Umlaut directory and run:

./script/generate umlaut_local

Don't worry if you run this twice; it'll warn and prompt you before over-writing any existing files.

Tasks for local SVN management

We also provide some rake tasks to perform svn operations on all of these local locations at once.

rake umlaut_lcl:import_to_svn

You've generated all this stuff, and added your own local content. Run this to add it all to your own local SVN--or any other SVN you have access to to store your local config. You'll be prompted for an SVN base path. Make sure to run umlaut_lcl:commit too, this operation does not commit any files!

rake umlaut_lcl:checkout

Let's say you already have your local files in your own SVN, but now you doing a new Umlaut install for whatever reason. This rake task will pull all your local stuff down en masse and put it into the new install. You will be prompted for an SVN base.

rake umlaut_lcl:update

svn update all local directory locations.

rake umlaut_lcl:commit

svn commit all local directory locations.

rake umlaut_lcl:status

Runs svn status on all local directory locations at once.

If you need to create an svn repo on a Linux box it's as easy as:

mkdir /home/username/svn

svnadmin create /home/username/svn

Then you can run the above rake tasks.

A Locally Customized Layout

In addition to config files in umlaut_config, the one piece of local customization that almost everyone will do first is creating a local layout for your own look and feel. This can be fairly easily done even to those new to Ruby Rails. In Rails, there are template wrappers (or wrapper templates?) known as 'layouts'. We'll walk you through customizing an Umlaut layout to your local needs, and saving it in a local location.

Start out by copying the default resolver layout from $Umlaut/app/views/layouts/resolve_basic.rhtml to $Umlaut/app/views/layouts/local/myuniversity_resolve_layout.rhtml.

It's this copy now in local that you'll modify.

• Don't have a directory at .../layouts/local? See the above section! You need to run "rake umlaut_lcl:generate" and it'll make one for you. Or you could just create it by hand.
• In addition to the resolve_basic.rhtml, some other example locally customized resolve layouts are distributed with umlaut in $Umlaut/app/views/layouts/distribution. You could start with one of these instead, or use them to see what's possible.

Now edit this local copy to your heart's content. Change the header, change the footer. Link to a different stylesheet (perhaps your want to keep your own custom stylesheet in $Umlaut/public/local, and use the Rails methods to link to it). You should not disturb the declerations that looks like this:

render(:partial => "layout_helpers/resolve_head_content" )

and

render(:partial => "layout_helpers/resolve_body_open" )

Because they bring in some standard Umlaut functionality. But just about everything else is fair game.

Now you've got your layout all customized, how do you get your Umlaut installation to use it? (Of course, really, you'd want to get Umlaut to use it as you are developing it, so you can see how it looks!).

In your local config file at $Umlaut/config/umlaut_config/environment.rb, add (or uncomment) this line:

config.app_config.resolve_layout = "local/myuniversity_resolve_layout.rhtml"

Start (or restart) Umlaut, and it should now be using your localized layout. Neat, huh?

This gives an example of how Umlaut localization is meant to work in general. Note how you didn't need to edit any of the files that came from Umlaut SVN to make this customization.