A few months ago I created BreadcrumbsOnRails to solve the recurrent pattern of creating breadcrumb navigations with Ruby on Rails. Today I’m open-sourcing the project and the code is now available on GitHub.
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.
You can install BreadcrumbsOnRails as a Gem
1 | $ gem install breadcrumbs_on_rails --source http://gemcutter.org |
1 2 3 4 5 6 7 8 | Rails::Initializer.run do |config| # other configurations # ... config.gem "breadcrumbs_on_rails", :source => "http://gemcutter.org" end |
or as a Rails plugin
1 | $ 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.
1 2 3 4 5 6 7 8 9 10 11 12 | 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.
1 2 3 4 5 6 7 8 9 10 11 12 | <!--<span class="hiddenSpellError" pre=""-->DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 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.
1 2 3 | <body> <%= render_breadcrumbs :separator => ' / ' %> </body> |
More complex customizations require a custom Builder.
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 | 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.
1 2 3 4 5 6 7 8 | 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.
1 2 3 4 5 6 7 | class MyController # The Name is set to the value returned by # the :root_name method. add_breadcrumb "homepage", "http://example.com/" end |
Restricting breadcrum 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.
1 2 3 4 5 6 7 8 9 10 11 12 | 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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | # 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.
1 2 3 4 5 6 7 | 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 |
Resources
BreadcrumbsOnRails is released under the terms of the MIT License. The source code is available on GitHub.
BreadcrumbsOnRails is not suitable for a generic navigation menu. If you are looking for a way to create a generic or a tabbed navigation menu, check out my TabsOnRails plugin.
