Breadcrumbs On Rails

BreadcrumbsOnRails is a simple Ruby on Rails plugin for creating and managing a breadcrumb navigation for a Rails project. It provides helpers for creating navigation elements with a flexible interface.

Requirements

  • Ruby >= 1.8.6

  • Rails 2.2.x, 2.3.x or 3.0 (see section Rails 3 below)

Rails Installation

As a Gem

This is the preferred way to install BreadcrumbsOnRails and the best way if you want install a stable version. The GEM is hosted on RubyGems.

$ gem install breadcrumbs_on_rails

Rails 2.2.x and 2.3.x

With Rails 2.2.x and 2.3.x, you need to specify the GEM dependency in your environment.rb file so that Rails will automatically include the library on startup.

Rails::Initializer.run do |config|

  # other configurations
  # ...

  config.gem "breadcrumbs_on_rails"

end

Rails 3

With Rails 3, you need to specify the GEM dependency in your Gemfile file so that Bundler can resolve, download and install the library.

gem "breadcrumbs_on_rails"

As a Plugin

This is the preferred way if you want to live on the edge and install a development version.

$ script/plugin install git://github.com/weppos/breadcrumbs_on_rails.git

Usage

Creating a breadcrumb navigation menu in your Rails app using BreadcrumbsOnRails is really straightforward.

In your controller, call add_breadcrumb to push a new element on the breadcrumb stack. add_breadcrumb requires two arguments: the name of the breadcrumb and the target path.

class MyController

  add_breadcrumb "home", root_path
  add_breadcrumb "my", my_path

  def index
    # ...

    add_breadcrumb "index", index_path
  end

end

In your view, you can render the breadcrumb menu with the render_breadcrumbs helper.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>untitled</title>
</head>

<body>
  <%= render_breadcrumbs %>
</body>
</html>

render_breadcrumbs understands a limited set of options. For example, you can pass change the default separator with the :separator option.

<body>
  <%= render_breadcrumbs :separator => ' / ' %>
</body>

More complex customizations require a custom Builder (documentation yet to come).

Breadcrumb Element

A breadcrumbs menu is composed by a number of Element objects. Each object contains two attributes: the name of the breadcrumb and the target path.

When you call add_breadcrumb, the method automatically creates a new Element object for you and append it to the breadcrumbs stack. Element name and path can be one of the following Ruby types:

  • Symbol

  • Proc

  • String

Symbol

If the value is a Symbol, the library calls the corresponding method defined in the same context the and sets the Element attribute to the returned value.

class MyController

  # The Name is set to the value returned by
  # the :root_name method.
  add_breadcrumb :root_name, root_path

  protected

    def root_name
      "the name"
    end

end

Proc

If the value is a Proc, the library calls the proc passing the current view context as argument and sets the Element attribute to the returned value. This is useful if you want to postpone the execution to get access to some special methods/variables created in your controller action.

class MyController

  # The Name is set to the value returned by
  # the :root_name method.
  add_breadcrumb Proc.new { |c| c.my_helper_method },
                 root_path

end

String

If the value is a Proc, the library sets the Element attribute to the string value.

class MyController

  # The Name is set to the value returned by
  # the :root_name method.
  add_breadcrumb "homepage", "http://example.com/"

end

Restricting breadcrumb scope

The add_breadcrumb method understands all options you are used to pass to a Rails controller filter. In fact, behind the scenes this method uses a before_filter to store the tab in the @breadcrumbs variable.

Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.

class PostsController < ApplicationController
  add_breadcrumb "admin", admin_path
  add_breadcrumb "posts, posts_path, :only => %w(index show)
end

class ApplicationController < ActionController::Base
  add_breadcrumb "admin", admin_path, :if => :admin_controller?

  def admin_controller?
    self.class.name =~ /^Admin(::|Controller)/
  end
end

Internationalization and Localization

BreadcrumbsOnRails is compatible with the standard Rails internationalization framework.

For example, if you want to localize your menu, define a new breadcrumbs node in your .yml file with all the keys for your elements.

# config/locales/en.yml
en:
  breadcrumbs:
    homepage: Homepage
    first: First
    second: Second
    third: Third

# config/locales/it.yml
it:
  breadcrumbs:
    homepage: Homepage
    first: Primo
    second: Secondo
    third: Terzo

In your controller, use the I18n.t method.

class PostsController < ApplicationController
  add_breadcrumb I18n.t("breadcrumbs.first"), first_path
  add_breadcrumb I18n.t("breadcrumbs.second"), second_path, :only => %w(second)
  add_breadcrumb I18n.t("breadcrumbs.third"), third_path, :only => %w(third)
end

class ApplicationController < ActionController::Base
  add_breadcrumb I18n.t("breadcrumbs.homepage"), root_path
end

Rails 3

This plugin is “partially” compatible with Rails 3. The first attempt to create an unique release compatible with both Rails 2.x and Rails 3 failed due to some Rails 3 internal changes (see github.com/weppos/breadcrumbs_on_rails/commit/b25885ceb293193b6b264177769f003985df3bff).

This version is specifically packaged and tested against Rails 2.3.x, but you can use it in a Rails 3 application by manually including the BreadcrumbsOnRails::ControllerMixin mixin in your ApplicationController.

class ApplicationController < ActionController::Base
  include BreadcrumbsOnRails::ControllerMixin
end

A Rails 3 version will be available very soon.

Author

Resources

License

Copyright © 2009-2010 Simone Carletti, BreadcrumbsOnRails is released under the MIT license.