Theme Developer's Guide: Navigation Helpers

Navigation

The navigation helper builds single- or multi-level navigation trees, based on the structure of your site tree. Complex site menus can be created that are automatically kept up to date when pages are added to the site. In this site, the navigation helper is used to render the primary navigation in the header, as well as the subnavigation to the right.

Navigation trees are rendered as nested unordered lists (UL), containing links and span tags. HTML classes are added to the list items, allowing the lists to be styled as necessary using CSS:

• current — if the item corresponds to the current page
• child-current — if any items beneath this one correspond to the current page
• nav-first — for the first item in the list or sublist
• nav-last — for the last item in the list or sublist
• A parameterized version of the current node label preceded by nav-
  e.g. An item labelled About Us has a class of nav-about-us

The navigation helper accepts the following options:

• :id — the HTML id attribute to apply to the top-level UL
• :class — the HTML class attribute to apply to the top-level UL
• :depth — the maximum depth tree to render (0 or 1 will both render a flat list)
• :root — the top-level node of the tree (can be given as a node, node id or node label)
• :include_root — whether to include the :root node in the tree (default is false)
• :except — an Array of node labels to explicitly exclude from the navigation tree

Example: primary navigation

 <%= navigation :depth => 2, :id => "primary-nav" %>

Output:

<ul id="primary-nav">
  <li class="nav-home nav-first"><a href="/"><span>Home</span></a></li>
  <li class="nav-about child-current">
    <span>About</span>
    <ul>
      <li class="nav-the-team nav-first current"><a href="/about/the-team"><span>The Team</span></a></li>
      <li class="nav-history nav-last"><a href="/about/history"><span>History</span></a></li>
    </ul>
  </li>
  <li class="nav-contact nav-last"><a href="/contact"><span>Contact</span></a></li>
</ul>

Example: subnavigation

<%= navigation :depth => 1, :class => "subnav", :root => node %>

Output:

<ul class="subnav">
  <li class="nav-the-team nav-first"><a href="/about/the-team"><span>The Team</span></a></li>
  <li class="nav-history nav-last"><a href="/about/history"><span>History</span></a></li>
</ul>

Breadcrumbs

Breadcrumb trails (such as the one below the main header on this site) can be easily added to your templates or layouts using the breadcrumbs helper. Wheelhouse automatically builds a breadcrumb trail based on the location of the current page within the site tree, and will prepend the home page.

Two styles of breadcrumbs are possible — an ordered list (OL) of links (the default style), or as simple inline content. The helper accepts an options hash with the following options:

• :style — pass :inline to render inline, otherwise will render as an ordered list (default)
• :separator — sets a custom item separator when rendering inline breadcrumbs (default is >)
• All other options (e.g. :class or :id) are set as attributes on the OL element

Example: breadcrumb list (default)

<%= breadcrumbs %>

Output:

<ol class="breadcrumbs">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
  <li><span>The Team</span></li>
</ol>

Example: inline breadcrumbs

<p><%= breadcrumbs :style => :inline, :separator => "|" %></p>

Output:

<p><a href="/">Home</a> | <a href="/about">About</a> | <span>The Team</span></p>

Additional breadcrumbs can be appended by calling the breadcrumb helper method before outputting breadcrumbs. This method takes the breadcrumb text and path as its parameters, but will use the current request path if no other path is given. This method is generally only used in templates provided by plugins, such as for a blog post.

Example: adding a breadcrumb for the current blog post

<% breadcrumb @post.title, @post %>