This theme support has been turned into a gem and ported to Rails 3.0 by Pierre Yager and Sylvain Claudel (www.crisalid.com)

Theme Support for Rails Applications

This plugin provides support for themes to the rails application environment. It supports theme specific images, stylesheets, javascripts, and views. The views can be in ERb (rhtml) or liquid formats. Optionally, you can configure the theme system to ignore any templates except liquid ones.

Creating a Theme using Theme Support ==

This plugin automatically makes any patches needed for theme support. Use the following command to create the file structure needed (replace YOUR_THEME_NAME with the name of your theme):

rails generate theme YOUR_THEME_NAME

The following theme folder structure will generate in your app code:

$app_root
  themes/
    [theme_name]
      images/
      stylesheets/
      javascripts/
      views/           <- you can override application views
        layouts/       <- layout .rhtml or .liquid templates
      about.markdown
      preview.png

Caveats==

When run in production mode, it will automatically cache the theme files so that the web-server will deliver them in subsequent requests.

It bears noting that, like Typo, this will mean your apache/fcgi process will need write permissions. This could be a possible security vulnerability. For those of us using passanger and mongrels, more information will follow.

With that in mind, it is best to pre-cache all of the theme files by using the included rake tasks:

$ rake themes:cache:create

The theme file cache generates the following file structure:

$app_root
  public/
    themes/
      [theme_name]/
        images/
        stylesheets/
        javascripts/

There are other rake tasks available:

- themes:cache:create
- themes:cache:remove
- themes:cache:update

Using your new Theme in your app code ==

You specify which theme to use in your controller by using the ‘theme’ helper. It’s used just like the ‘layout’ helper. In fact, you can use them both simultaneously. The following will render actions using the ‘application’ layout in the ‘blue_bird’ theme (theme/blue_bird/views/layouts/application.html.erb):

class ApplicationController < ActionController::Base
  layout 'application'

  theme 'blue_bird'

  ...
end

You can also defer the theme lookup to a controller method:

class ApplicationController < ActionController::Base
  layout 'application'

  theme :get_theme

  def get_theme

    # If you let the user choose their own theme, you might
    # add a User#theme field...

    current_user.theme
  end

  ...
end

Note: By setting the theme in the ApplicationController you can set the theme for the whole application.

Using themes in your Views ==

ERb:

In your application views, there are theme specific helper tags available to you.

- theme_image_tag
- theme_image_path
- theme_javascript_include_tag
- theme_javascript_path
- theme_stylesheet_link_tag
- theme_stylesheet_path

ERB Example :

# Note my theme is called "blue_bird" and my css file is called "style.css"
<%= theme_stylesheet_link_tag 'blue_bird', 'style' %>

LIQUID:

Liquid templates there is a single helper, themeitem, that will determine the path base on the theme file extension. Here’s how you’d use it:

<link rel="StyleSheet" href="{% themeitem %} default.css {% endthemeitem %}" />
...
<img src="{% themeitem %} logo.png {% endthemeitem %}" />

The output from those two calls are:

<link rel="StyleSheet" href="/themes/[current_theme]/stylesheets/default.css" />
...
<img src="/themes/[current_theme]/images/logo.png" />

ActionMailer Support ==

New in version 1.4 is ActionMailer support. Note, this is still experimental. However, if you would like your themes to be able to override your ActionMailer views, you can send the theme in your deliver_* method call. For example, assuming we have an ActionMailer class named Mailer, and have implemented theme_support as shown above, here’s how you would allowing themes in emails:

def send_email
  Mailer.deliver_my_email( 'a variable', :theme=>get_theme )
end

Contributors

The theme_support plugin includes patches from the following:

agkr
D.J. Vogel
Pierre Yager (zedalaye) and Sylvain Claudel (riven)

Thanks guys!

Changelog

 3.0.7 - Doesn't work for render_to_string because the hack is too high in the stack, render use render_to_string. Fixed

 3.0.6 - We didn't need to preload cache (rake themes:cache:update) in development

 3.0.5 - html_safe on helpers, Theme model and controller become Themesupport model and controller

 3.0.4 - [BUG] override view when we use explicitely render 

 3.0.3 - Hack which uses layout theme but crashes if it doesn't exist ! Now it loads the default layout

 3.0.2 - Don't load a nil theme

 3.0.1 - layout :mymethod works again

 3.0.0 - Converted theme_support plugin into a Rails 3.0 compatible gem.

 1.5.0 - Using jystewart's fork of the original github theme_support, the helper methods should
		  work in Rails 2.2.2.  ReadME fixed.  Layouts changed to reflect Rails conventions: e.g.,
		  layouts are now under views, application.html.erb used to reflect standard naming
		  conventions.

 1.4.0 - Better support for Rails 1.1+. Updated the liquid themeitem tag.
         Liquid layouts are no longer generated by default.Added a couple 
         of patches. One allows theme sub-directories. For example, you 
         can have:

           [theme_dir]
             stylesheets/
               admin/
                 main.css

         Added experimental support for themeing ActionMailer classes.
         They work as normal, if you want to all theme's to override the
         .rhtml|.liquid views, send the theme in the deliver_* method. For
         example:

           Mailer.deliver_signup( user, :theme=>get_theme() )

         In that example, `get_theme` is a method on the controller and at 
         the top we've used:

           layout 'default'
           theme :get_theme

 1.3.0 - The theme_system component is no longer needed. All of the
         theme support is driven by a single plugin named, oddly enough, 
         'theme_support'. Also improved theme route support. Instead of
         overriding RouteSet#reload, RouteSet#draw is overridden, making
         the theme support entirely transparent -- hopefully ;-) 

 1.2.2 - More Bug-fixes.

 1.2.1 - Bug-fixes and documentation clean up.

 1.2.0 - Updated actionview_ex with the new render_file additions from 
         Typo. Renamed the rake tasks so that they all start with 
         'theme' (theme_create_cache, theme_remove_cache, 
         theme_update_cache). You can update the system files by running:

           $ ./script/generate theme _system_

         Full support for Liquid templates, as well as an option to only
         allow Liquid templates in a theme.

 1.1.1 - Added rake tasks for pre-caching the themes, and removing the
         cached themes. 

 1.1.0 - [Breaking] Abstraction of the Typo theme system. The themes are
         now the same as is used in Typo. The theme engine itself is a
         combination of plugins and a component. No more symlinks, thank
         goodness.

 1.0.2 - The current_theme is now retrieved from the controller. Where
         symlinks are created on *nix systems, shortcuts are created 
         on Windows if Win32Utils is installed.

 1.0.1 - Added 'themes' directory, theme definition file, and symlinks 
         to the appropriate directories on supported platforms.

 1.0.0 - Initial release