Supporting Themes In Your Rails Application
Update: There's an updated version of the theme_generator. See the blog post or download it.
I was pretty impressed after looking at the theme support in Typo 2.5. However, I don’t think it’s a system that you should replicate if you want your application to support simple themes.
Before I get too far along let me make it clear that it’s not my intention to cast aspersions on Typo, it’s an excellent tool. In fact, I plan on switching to it from WordPress in the near future.
My issue with Typo’s theme scheme (heh) is that it doesn’t leverage the web-server as it should. Rails is impressive, and it’s caching is quite good. But web-servers like Apache have been around for many years. They are really good at what they do, so let them do it! Rails can’t compete with the server’s ability to deliver static content like CSS and graphics.
Following is how I’ve been implementing themes in Rails applications. In addition to relying on the web-server to provide static files, it also leverages existing Rails infrastructure wherever possible. Bear in mind, I’m not suggesting the following to be an end-all solution. Nor is it a drop-in replacement for Typo’s theme support. Merely think of it as a good starting point.
I’ve been using this approach enough that I’ve created a generator for it.
Usage
After you’ve installed the generator, just call it with the name of the theme you’d like to create.
./script/generate theme blue-bird
It will then add theme_engine.rb to your lib/ folder and create the required file structure.
Note: On Windows, it looks more like:
ruby script\\generate theme blue-bird
File Structure
Let’s start by having a look at the file structure it creates. Here’s an example for a theme named ‘blue-bird’.
app/
views/
layouts/
themes/
blue-bird/
public/
themes/
blue-bird/
images/
javascripts/
theme.css
Just from looking at that, you can probably get a good idea where I’m going.
Static Files
All of the static files, CSS, Images, and JavaScripts are under the app/public/themes directory, as they should be. Apache (or lighttpd, or whatever) will happily serve these up for us.
To reference theme-specific images from the CSS it’s as simple as:
[code lang="css"] BODY { background: url( images/my-bg.png ); } [/code]Be sure to use a relative path to the image. CSS will look for images relative to the CSS file, not the page, remember?
Layouts
You’ll notice under the app/views/layouts folder, I’ve added a theme structure similar to the one under app/public/. As an example, app/views/layouts/themes/default/main.rhtml is the main layout for the ‘default’ theme.
In your controller, you’ll tell Rails that you want a themed layout like this:
[code lang="ruby"] class MyController << ApplicationController layout :themed_layout end [/code]Current Theme
The only thing that’s left to your controller is indicating which theme is currently active. It’s as simple as overriding the current_theme method.
[code lang="ruby"] class MyController << ApplicationController layout :themed_layout def current_theme 'blue-bird' end end [/code]To set the theme for the entire application, you can add that to your ApplicationController instead (in app/controllers/application.rb).
Tag Helpers
To aid in retrieving themed media, helper methods have been added to the ActionView::Helpers::AssetTagHelper module.
- theme_image_path
- theme_stylesheet_path
- theme_javascript_path
- theme_stylesheet_link_tag
- [More to come…]
Usage is generally quite simple. In your view, if you want to reference a themed image:
[code lang="xml"]
[/code]
Last, But Not Least
This needs to be included at the bottom of your environments.rb:
[code lang="ruby"]require_dependency 'theme_engine'[/code]That’s it really—pretty straight forward. If you look at the theme_engine.rb you’ll see it’s a less-is-more type solution.
In the next few days I’ll polish the theme_engine some more, based on the feedback y’all provide, and refactor it into a plugin.
