Breadcrumb Trail

Helps you create a breadcrumb system for your Rails application. Better than any other library, guaranteed^*.

Installation

Add this line to your application's Gemfile:

gem 'breadcrumb_trail'

And you're done!

Usage

The gem adds some nice methods to your controller:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base

  breadcrumb name: "Home", path: :root_path
end

# app/controllers/articles_controller.rb
class ArticlesController < ApplicationController
  breadcrumb name: "Articles", path: :articles_path

  def show
    @article = Article.find(params[:id])
    breadcrumb name: @article.name, path: article_path(@article)
    breadcrumbs # => returns all of your breadcrumbs
  end
end

<!-- app/views/layouts/application.html.erb -->
<!-- ... -->
<%= render_breadcrumbs outer: "ul" %>
<!-- ... -->

...all results in (with some assumptions):

<!-- ... -->
<ul>
  <li><a href="/">Home</a></li>
  <li><a href="/articles">Articles</a></li>
  <li><a href="/articles/1">Hello, World</a></li>
</ul>
<!-- ... -->

You can pass #breadcrumb some options, which it'll use as HTML options by default.

Simple, right?

Builders

#render_breadcrumbs takes an option for a builder, or defaults to one if you don't provide it. There are two default builders: HTMLBuilder and BlockBuilder. If you provide a block to #render_breadcrumbs, then BlockBuilder is used; otherwise, HTMLBuilder is used.

HTMLBuilder

HTMLBuilder builds a sensible block of HTML based on some options. The exact options you can provide are:

• outer: The outer tag that is used. The default for this is ol. If this is nil, then no outer tag is rendered.
• inner: The inner tag that is used. The default for this is li. If this is nil, then no inner tag is rendered.
• outer_options: The html attributes that are used for the outer tag. By default, there are no options. If you want to add class="some-class", this is the place to provide it.
• inner_options: The html attributes that are used for the inner tag. By default, there are no options. If you want to add class="some-class", this is the place to provide it.

That's it!

BlockBuilder

BlockBuilder yields each breadcrumb to the given block. Each breadcrumb has three attributes: name, path, and options. To recreate the default output of HTMLBuilder, you'd have to do this with BlockBuilder:

<!-- ... -->
<ol>
<%= render_breadcrumbs do |breadcrumb| %>
  <li><%= link_to(breadcrumb.name, breadcrumb.path, breadcrumb.options) %></li>
<%= end %>
</ol>
<!-- ... -->

Your Own Builder

You don't have to use one of these. You can use your own builder. However, if you're using a builder because the default builders don't provide a feature you like, open an issue!

Your builder only needs to subclass BreadcrumbTrail::Builder and define the method #call, and that's it! Then, you pass the builder to #render_breadcrumbs with the builder option:

<!-- ... -->
<%= render_breadcrumbs builder: MyCustomBuilder %>
<!-- ... -->

Any options passed to #render_breadcrumbs are passed to your builder's #initialize via the last argument.

Contributing

1. Fork it (https://github.com/medcat/breadcrumb_trail/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

^*: Not guaranteed.