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

Rails 3 or Rails 4

Please note

BreadcrumbsOnRails 2.x requires Rails 3. Use BreadcrumbsOnRails 1.x with Rails 2.
BreadcrumbsOnRails doesn't work with Rails 2.1 or lower.

Installation

RubyGems is the preferred way to install BreadcrumbsOnRails and the best way if you want install a stable version.

$ gem install breadcrumbs_on_rails

Specify the Gem dependency in the Bundler Gemfile.

gem "breadcrumbs_on_rails"

Use Bundler and the :git option if you want to grab the latest version from the Git repository.

Basic 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

The third, optional argument is a Hash of options to customize the breadcrumb link.

class MyController
  add_breadcrumb "home", :root_path, :options => { :title => "Home" }

  def index
    add_breadcrumb "index", index_path, :title => "Back to the Index"
  end
end

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

<!DOCTYPE html>
<html>
<head>
  <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>

Current possible options are:

:separator
:tag

To use with Bootstrap you might use the following:

<body>
  <ol class="breadcrumb">
    <%= render_breadcrumbs :tag => :li, :separator => "" %>
  </ol>
</body>

More complex customizations require a custom Builder.

Read the documentation to learn more about advanced usage and builders.

Credits

BreadcrumbsOnRails was created and is maintained by Simone Carletti. Many improvements and bugfixes were contributed by the open source community.

Contributing

Direct questions and discussions to Stack Overflow.

Pull requests are very welcome! Please include tests for every patch, and create a topic branch for every separate change you make.

Report issues or feature requests to GitHub Issues.

johnkoht/breadcrumbs_on_rails