Theme Developer's Guide: Writing Templates

Introduction to Layouts

Wheelhouse themes use the same template and layout model used by Ruby on Rails. If you are coming from another CMS which doesn't use layouts, you will quickly see that layouts make handling common template areas (headers, footers, etc) much easier and less error-prone.

Layouts act as a container for your templates, generally containing the main HTML tags (html, head, body) as well as any common wrapper elements (page title, navigation, breadcrumbs, etc). The yield keyword in your layout file passes control to the template, and inserts the template's content into the layout.

Layouts and templates are combined to produce the final output


Each template requires a name, which can be assigned by setting This will usually be the first line of your template file. For example:

<% = "Custom Template" %>

If you are writing a template for a resource type that is not a regular page, you must specify the resource type using template.resource=.

<% template.resource = Blog::Post %>

Finally, page caching can be disabled by setting template.cache:

<% template.cache = false %>


The default layout for your template is named default.html.erb (or default.html.haml for Haml templates) and is located within the layouts/ folder within the theme's templates. Additional layouts can be added within this layouts/ folder.

As with templates, layouts also require a name (assigned via

<% = "Alternative Layout" %>

Additional Resources