Umlaut Local Configuration Architecture
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:
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:
Don't worry if you run this twice; it'll warn and prompt you before over-writing any existing files.
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 to help you control them in your own local svn.
- 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:
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" )
- 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.