Assets Pipeline Integration

There are at least two ideas regarding how to organize the themes on a rails app with assets pipeline. Both methods are equally valid and have their own inherent advantages and disadvantages.

Split Theme Storage

The Rails asset pipeline is for storing “static” assets (images, javascripts, stylesheets) and should not be storing “traditional” MVC components (in this case, views). This method will show you how to put your theme assets in the asset pipeline and maintain your views under {Rails.root}/app/views.

Create your directory structure for your application like below:

{Rails.root}
  app/
    assets/
      images/           <-- default asset pipeline folder
      javascripts/      <-- default asset pipeline folder
      stylesheets/      <-- default asset pipeline folder
      themes/           <-- your themes asset pipeline folder
        [theme_name]
          images/
          stylesheets/
          javascripts/
    views/
      themes/           <-- themes views folder (lives under the built-in Rails views folder)
        [theme_name]  
          layouts/      <- layout templates for theme
          [your_controller(s)]

Create an initializer for themes in your {Rails.root}/config/initializers directory and set up your paths appropriately.

ThemesForRails.config do |config|
  # themes_dir is used to allow ThemesForRails to list available themes. It is not used to resolve any paths or routes.
  config.themes_dir = ":root/app/assets/themes"

  # assets_dir is the path to your theme assets.
  config.assets_dir = ":root/app/assets/themes/:name"

  # views_dir is the path to your theme views
  config.views_dir =  ":root/app/views/themes/:name"

  # themes_routes_dir is the asset pipeline route base. 
  # Because of the way the asset pipeline resolves paths, you do
  # not need to include the 'themes' folder in your route dir.
  #
  # for example, to get application.css for the default theme, 
  # your URL route should be : /assets/default/stylesheets/application.css
  config.themes_routes_dir = "assets"
end

Unified Theme Storage

You may want to keep all your theme assets and views combined under a single themes directory but still take advantage of the asset pipeline. This could allow for easier deployment of individual theme packages to different environments, or to easily distribute themes.

Create your directory structure for your application like below:

{Rails.root}
  app/
    assets/
      images/           <-- default asset pipeline folder
      javascripts/      <-- default asset pipeline folder
      stylesheets/      <-- default asset pipeline folder
      themes/           <-- your themes root folder
        [theme_name]
          images/
          stylesheets/
          javascripts/
          views/        <-- themes views folder (lives under the theme folder inside the asset pipeline)
            layouts/      <- layout templates for theme
            [your_controller(s)]

Add this to your ThemesForRails configuration file.

ThemesForRails.config do |config|
  # themes_dir is used to allow ThemesForRails to list available themes. It is not used to resolve any paths or routes.
  config.themes_dir = ":root/app/assets/themes"

  # assets_dir is the path to your theme assets.
  config.assets_dir = ":root/app/assets/themes/:name"

  # views_dir is the path to your theme views
  config.views_dir =  ":root/app/assets/themes/:name/views"

  # themes_routes_dir is the asset pipeline route base. 
  # Because of the way the asset pipeline resolves paths, you do
  # not need to include the 'themes' folder in your route dir.
  #
  # for example, to get application.css for the default theme, 
  # your URL route should be : /assets/default/stylesheets/application.css
  config.themes_routes_dir = "assets" 
end

Stylesheet configuration

In your theme stylesheets directory, you can create an application.css file using the Sprockets require methods as usual. Because of the way the asset pipeline resolves paths, if you are storing your themes in `{Rails.root}/app/assets/themes/{images,javascripts,stylesheets}` you would NOT include the ‘themes’ in your require path. If you do not preface your require with a path, it will pull the prefaced stylesheet from the `{Rails.root}/app/assets/stylesheets` path. See the example below:

/*
 *= require global_stylesheet_name
 *= require theme_name/stylesheets/stylesheet_name
 */

Javascript configuration

In your theme javascripts directory, you can create an application.js file using the Sprockets require methods as usual. Because of the way the asset pipeline resolves paths, if you are storing your themes in `{Rails.root}/app/assets/themes/{images,javascripts,stylesheets}` you would NOT include the ‘themes’ in your require path. If you do not preface your require with a path, it will pull the prefaced script from the `{Rails.root}/app/assets/javascripts` path. See the example below:

//= require jquery
//= require theme_name/javascripts/script_name