Easy and flexible breadcrumbs for Rails

Most projects I work on require some implementation of breadcrumbs. Unfortunately most solutions that I found take the very simplistic approach: they split the URL and present each part as a link. I really have a hard time imagining that this can be sufficient for any non-trivial app.

I also found session-based implementation, but according to the above mentioned Wikipedia article classification these are path-style breadcrumbs, while I need location-style with a little bit of attribute-style mixed in where needed. That is, the breadcrumbs should normally reflect the page’s location in some (virtual) website hierarchy. Sometimes, while browsing things that are naturally hierarchical (like forum threads/posts, category trees and so on), the breadcrumb trail should also reflect this hierarchy. Read on to see my take on this problem.

The requirements

First, let’s formulate the requirements for the breadcrumbs solution.

1. It should be a list of links with descriptions, except for the last element, which should not be clickable because it represents current page.
2. It should have syntax that is easy to use, ideally something like: add_breadcrumb 'Description', some_path
3. It should allow us to add arbitrary number of elements, both statically and dynamically.
4. The static parts should be similar to filters:
   1. declared at one place (e.g. at the top of the controller) not littered around actions or views,
   2. inheritable (so you can declare home link only once, in your ApplicationController),
   3. with easily recognizable order,
   4. and support for filter options like :only or :except.
5. The dynamic parts can be added at any time during the request processing, from actions, filters of views, if necessary.

Looks like a lot of hard work? Maybe. But my priority was flexibility and ease of use, not necessarily ease of implementation. I want to be able to do things like this:

Simple example

class ApplicationController < ActionController::Base
  add_breadcrumb 'Home', '/'
  ...
end  
class ThingsController < ApplicationController
  add_breadcrumb 'Things', 'things_path'
  add_breadcrumb 'Create a new thing', '', :only => [:new, :create]
  add_breadcrumb 'Edit a thing', '', :only => [:edit, :update]
  
  def show
    @thing = Thing.find(params[:id])
    add_breadcrumb @thing.name, ''
  end
  ...
end

With this setup, we get breadcrumbs like Home > Things for things index, Home > Things > Create a new thing for new thing or Home > Things > some name for show action.

Notes

• We need to quote *_path and *_url (like this: 'things_path') when outside of actions due to the way these methods are implemented in Rails. I stretched requirement #2 here but I think this is really only a minor inconvenience. When you forget to do this, you’ll get an undefined method error. The quoted string will be eval-ed when the request is processed, which is of course not the cleanest solution, but works for me.
• When the added element is guaranteed to be the last, we don’t have to provide the URL for it.
• Although it may seem that :new is sufficient for the new thing form, we need to add :create to have the breadcrumb defined when the validation fails and the form is redisplayed (same for :edit and :update, respectively). This may look like a redundancy but that’s how Rails works. Alternatively you can add the breadcrumb from the new.html.erb template or inside the :create action. But I prefer to have them declared in one place if only possible.
• If you use add_breadcrumb in your ApplicationController, you must do it after the methods are defined (it should be under those methods).

Dynamic example

Now for something a little bit more dynamic, let’s assume we have a hierarchy of categories and while browsing a category we want the breadcrumb to show all the ancestor categories:

class CategoriesController < ApplicationController
  add_breadcrumb 'Categories', 'categories_path'
  
  def show
    @category = Category.find(params&#91;:id&#93;)
    set_breadcrumb_for @category
  end
  ...
private
  def set_breadcrumb_for cat
    set_breadcrumb_for cat.parent if cat.parent
    add_breadcrumb cat.name, "category_path(#{cat.id})"
  end
end
&#91;/sourcecode&#93;  

<p>This lets us have breadcrumbs like <em>Home &gt; Categories &gt; Root &gt; Parent &gt; Child</em> for tree-like category hierarchies. The <code>set_breadcrumb_for</code> method traverses all the parents of the category recursively until it finds the root category. I agree that the <code>"category_path(#{cat.id})"</code> part looks a little bit messy, but I couldn't find any cleaner way to do this with the <code>eval</code> solution I mentioned above. Any suggestions welcome.</p>

<h1>The implementation</h1>

<p>Now for the implementation. It's really quite trivial for the above defined set of the requirements. Just drop these two methods in your <code>ApplicationController</code>: </p>


class ApplicationController < ActionController::Base
  ...
protected
  def add_breadcrumb name, url = ''
    @breadcrumbs ||= &#91;&#93;
    url = eval(url) if url =~ /_path|_url|@/
    @breadcrumbs << &#91;name, url&#93;
  end

  def self.add_breadcrumb name, url, options = {}
    before_filter options do |controller|
      controller.send(:add_breadcrumb, name, url)
    end
  end
end
&#91;/sourcecode&#93;  

<p>We need two versions of <code>add_breadcrumb</code> method. The first one (which is an instance method) is <strong>responsible for constructing the actual breadcrumb list</strong>. It is called several times during request processing. As we can see <code>@breadcrumbs</code> is just a list of two element lists, containing description and a URL.</p>

<p>The second version is a class method that we can use in declarations at the top of our controllers. It just <strong>defines an unnamed <code>before_filter</code></strong> which, when called, uses the first version to add breadcrumb element. This way we get all the goodies (<code>:only</code>, <code>:except</code>, ordering) for free.</p>

<p>How to display the breadcrumbs? Put something like below to your layout and add HTML tags and styles as needed.</p>


<% if @breadcrumbs %>
  You are here: 
  <% @breadcrumbs&#91;0..-2&#93;.each do |txt, path| %>
    <%= link_to(h(txt), path) %> >
  <% end %>
  <%= h(@breadcrumbs.last.first) %>
<% end %>

And that’s it. I hope it works for you. Any suggestions and improvements welcome.

UPDATE: I just posted a followup about how to make breadcrumbs work in an internationalized application.

UPDATE #2: you can have problems with using add_breadcrumb in your ApplicationController, as noted by Vinay in the comments below. See notes above how to fix this.