slate blog

In my previous post, I provided an overview of how themes work in slate. This time I’ll show some examples.

content_for

As I mentioned before, slate themes do not use a custom template language. Rather, they are pure ERB templates that use some simple helpers. The most common of these helpers is content_for. When I first named this helper, I didn’t realize that Rails already has a helper by the same name, but luckily I haven’t needed to use the Rails version so I’m safe (for now).

The content_for helper essentially defines the editable area. Here’s a simple example:

  # themes/sample/index.rhtml

  <div id="sidebar">
    <%= content_for :sidebar -%>
  </div>

The argument :sidebar is the key for the area, used by slate to determine what content to load. The key can be a symbol or a string, though the convention is to use a symbol.

The powerful thing about this simple helper is that it renders a certain way based on the current view mode. The view mode is simply a passed param that is either draft, preview or production. Here’s the breakdown of what content_for renders in each view mode:

So, when we’re in slate admin and we view a page, all content_for helper calls render an admin interface for that area.

Changing themes

I mentioned last time that changing the theme for a site is essentially a matter of changing a single field in the database (the name of the theme associated with a site). This is possible because of the way content_for works. The only thing that distinguishes a content area is the key for the area. Since this key is independent of the theme and the database, all we need is for the template in the other theme to call content_for with the same key.

site_menu and link_to_page

One of the common elements of a theme is the navigation section. With slate, adding a dynamic site menu is easy:

  # themes/sample/index.rhtml

  <ul id="nav">
  <% for page in site_menu -%>
    <li><%= link_to_page page -%></li>
  <% end -%>
  </ul>

The site_menu helper returns an array of all visible top-level pages for the site. The link_to_page helper builds a link to the specified page, with a number of extra features. For one thing, it will attach the CSS class current-page to the link if it is the current page. It will attach the CSS class has-current-page to the link if it is an ancestor of the current page. Finally, it will generate different URLs based on the view mode (allowing easy navigation among pages within the admin interface).

partial

One more helper I’ll point out is partial, which provides an easy way to use partials in a theme. This is extremely handy because it allows the templates to follow the DRY principle. For example, this is the backpage.rhtml template for one of our sites:

  <%= partial('header') -%>
  <div id="viewport">
    <%= partial('navbar') -%>
    <%= content_for(:content) %>
    <%= partial('adobe_reader') -%>
  </div>
  <%= partial('footer') -%>    

There’s another extremely useful feature of the partial helper: shared partials. We have a shared/ directory which contains partials that can be used across multiple themes. One of these is the _masthead.rhtml partial, which contains the standard WVU logo and links. In the future, this partial will also be used to broadcast campus emergency notices, etc.

Including a shared partial is very similar to including a theme partial:

  <%= partial 'shared/masthead' -%>

This will include the contents of the file themes/shared/_masthead.rhtml.

Conclusion

Okay, that’s enough for now :-)