Ingredients

There are two types of ingredients in Blueprint: site ingredients, which live in the ingredients directory, and page ingredients, which allow you to use the functionality of a specific blueprint elsewhere in your code.

Site ingredients

Site ingredients take repeated content or code and store it in a file that can be accessed from anywhere in your site. Ingredients reside in the ingredients subdirectory of your site, and are named like this:

ingredient.render_type.renderer (eg: subnav.html.erb)

You can use one to clean up your layout, by placing lengthy meta-data into an ingredient and then calling it from the head of layout.html.erb; another good use of ingredients is to store sub-navigation patterns that aren't used on every page of your site.

Here's a sample ingredient called subnav.html.erb:

<% if @page.children.any? %>
  <ul class="subnav">
    <% @page.children.each do |child| %>
      <%= content_tag("li", link_to_page(child.title, child))
    <% end %>
  </ul>
<% end %>

You could then call it from the templates that needed it with:

<%= site_ingredient 'subnav' %>

Pro tip: You can pass an object or an array to a site ingredient template. This technique allows you to use a site ingredient much like you would a partial in a traditional Rails app. Here's an example:

In your Blog index template:

<% @posts.each do |post| %>
  <%= site_ingredient 'post_partial', :locals => { :post => post } %>
<% end %>

In your post_partial.html.erb template:

<div class="post">
  <h1><%= post.title %> &mdash; <%= post.publish_on.strftime("%d.%m.%y") %>
  <%= post.description_markup %>
</div>

This probably isn't the most useful example – after all, there's no reason not to simply include the ingredient snippet in the @posts loop - but it becomes extremely useful if you're repeating a pattern in several different templates. In this case, perhaps you're repeating the post pattern in post.html.erb and archive.html.erb as well - this means you only have to maintain that code in one spot.

Page ingredients

Page ingredients are more advanced. They allow you to grab content and functionality from a particular page and display it in your site - any blueprint template in the blueprints directory of your site can also be used in this way. Common usage includes displaying upcoming events in the sidebar of your homepage:

<%= page_ingredient 'events', 'upcoming' %>

The first argument is the page slug — in this case, you're referring to a top-level page called 'Events'. The second argument is the template, or action, name ('upcoming', corresponding to the upcoming.html.erb template).

If you want to use an alternative view of an action (say you've created kids.upcoming.html.erb, which shows only upcoming events tagged with 'kids'), then you have to add another argument; your ingredient call would look like this:

<%= page_ingredient 'events', 'upcoming', :template => 'kids %>

In this case, the first argument is the page slug, the second is the action, and the third points to the alternative template.

Just as for site ingredients, you can now pass local variables to your page ingredient template, in just the same way:

<%= page_ingredient 'events', 'upcoming', :locals => {:format => "brief"} %>

This allows you to access a local variable called format holding the string value "brief" in the target template.

Important: Do use page ingredients, because they make sites much easier to maintain. But be aware that each page ingredient goes back through the entire Blueprint request cycle, and therefore rendering a lot of page ingredients on a single page may be slow. Use them well and often, but wisely. (Site ingredients do not have the same speed concerns.)