Theme Developer's Guide: Anatomy of a Theme

A Wheelhouse theme consists of templates, layouts and assets (images, stylesheets, javascripts and possibly fonts), as well as a theme descriptor (theme.yml). On the previous page, we looked at the theme descriptor file; this page will introduce templates, layouts and assets.

Templates and Layouts

Templates are added to the templates directory and should be named with the extension .html.erb (or .html.haml for Haml templates). The Wheelhouse theme generator creates a default layout (templates/layouts/default.html.erb) and a default page template (templates/page.html.erb) as a starting point.

Any additional template and layout files added to the templates folder will then be available for selection by pages within the Wheelhouse admin area.

See Writing Templates for more information on how to write and customize templates and layouts.

Asset Files

Asset files are organized into three directories: images, stylesheets and javascripts. Any files added beneath these directories will be accessible at the URL /assets/themes/{theme}/{filename}.

For example, the file images/favicon.ico in a theme named demo is accessible from /assets/themes/demo/favicon.ico (note that the images/ folder is not part of the URL).

The Wheelhouse theme generator automatically creates some boilerplate asset files for you, including a (blank) favicon, a default Sass stylesheet, the jQuery library and the HTML5 javascript shim for HTML5 support in Internet Explorer 8 and below.

Asset Pipeline

Wheelhouse themes take full advantage of the Asset Pipeline, introduced in Rails 3.1.

Sass files (e.g. screen.css.sass) will be processed automatically and served at /assets/themes/demo/screen.css. Similarly, CoffeeScript files can be created with a .js.coffee extension and will be processed and served at /assets/themes/demo/filename.js.

If you'd prefer not to use Sass (or SCSS) and would rather stick with ordinary CSS, simply create a file with a .css extension and it will be served without preprocessing at /assets/themes/demo/filename.css.

When deploying, you should compile your assets by running rake assets:precompile. The following table shows where your assets will be compiled to:

Additional Resources

• Ruby on Rails Asset Pipeline Guide