Theme Developer's Guide: Asset Helpers

The Wheelhouse CMS asset helpers allow you to add stylesheets, javascript and images from your theme to your templates and layouts.

Asset fingerprinting

When running in production mode, asset digests (also known as fingerprints) will be automatically added to the filenames of stylesheets, javascripts and images provided by your theme to ensure that new versions will be downloaded when their contents are changed.

Using the asset helpers listed below ensures that the digests are properly added to asset paths. Whilst referencing an asset path statically will work, it may not be refreshed by the user's browser when the file is later updated.

To read more about asset fingerprinting, refer to the Asset Pipeline Rails Guide.

Stylesheets & JavaScripts

The stylesheet helper (a shorthand alias for the Rails stylesheet_link_tag helper) adds a stylesheet link tag to your template. The helper accepts one or more stylesheet names (either a stylesheet defined in your theme's assets/stylesheets directory or a complete URL) as well as an options hash, allowing you to specify a media type (default is 'screen').

Example:

<%= stylesheet "theme", "blog" %>
<%= stylesheet "print", :media => "print" %>
<%= stylesheet "http://fonts.googleapis.com/css?family=Marck+Script" %> 

Output:

<link href="/assets/themes/mytheme/theme.css" media="screen" rel="stylesheet" type="text/css" />
<link href="/assets/themes/mytheme/blog.css" media="screen" rel="stylesheet" type="text/css" />

<link href="/assets/themes/mytheme/print.css" media="print" rel="stylesheet" type="text/css" />

<link href="http://fonts.googleapis.com/css?family=Marck+Script" media="screen" rel="stylesheet" type="text/css" />

Similarly, the javascript helper (a shorthand alias for the Rails javascript_include_tag helper) adds JavaScript tags to the template.

Example:

<%= javascript "site" %>
<%= javascript "http://code.jquery.com/jquery-1.6.4.min.js" %>

Output:

<script src="/assets/themes/mytheme/site.js" type="text/javascript"></script>
<script src="http://code.jquery.com/jquery-1.6.4.min.js" type="text/javascript"></script> 

Images & Favicons

Images can be add using the image helper (a shorthand alias for the Rails image_tag helper).

Example:

<%= image("logo.png", :alt => "My Company") %>

Output:

<img src="/assets/themes/mytheme/logo.png" alt="My Company" />

The favicon helper (a shorthand alias for the Rails favicon_link_tag helper) inserts a favicon link tag, allowing you to define an icon for your site which will appear in the user's browser. It can also be used to set the shortcut icon used by iOS devices.

Example:

<%= favicon %>
<%= favicon 'ios-icon.png', :rel => 'apple-touch-icon', :type => 'image/png' %>

Output:

<link href="/assets/theme/mytheme/favicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon" />
<link href="/assets/theme/mytheme/ios-icon.png" rel="apple-touch-icon" type="image/png" />

Links

The link helper (a shorthand alias for the Rails link_to helper) creates a link (A) tag. Within Wheelhouse templates, links can be created by passing either a path or URL (as a String) or an addressable node (such as a Wheelhouse Page object).

Example:

<%= link "Link text", "/blog/feed.xml" %>
<%= link "External link", "http://www.google.com", :rel => "external" %>
<%= link "Site page", Wheelhouse::Page.get("Gallery"), :class => "gallery" %>

Output:

<a href="/blog/feed.xml">Link text</a>
<a href="http://www.google.com" rel="external">External link</a>
<a href="/gallery" class="gallery">Site page</a>

Rails helper aliases

The helper methods described above are shortened aliases of helpers provided by Ruby on Rails. If you prefer to use the original Rails helpers (listed in the table below), they will continue to work as normal, with no other changes necessary.