Ariane

A flexible breadcrumb system for Rails

View the Project on GitHub simonc/ariane

Ariane

Ariane is a flexible breadcrumb system for Rails. And it's fully compatible with the Twitter Bootstrap !

It works perfectly with Rails 3 and allows to use I18n.

Installation

Add the following line to your Gemfile:

gem 'ariane'

And then execute:

bundle

Requirements

Quickstart

To get started, define a before_filter in your ApplicationController and use it to add the first entry:

class ApplicationController < ActionController::Base
  before_filter :set_ariane

  protected

  def set_ariane
    ariane.add 'Home', root_path
  end
end

You can then add more entries from your other controllers:

class OtherController < ApplicationController
  protected

  def set_ariane
    super
    ariane.add 'Other', other_path
  end
end

Then in your layout, simply call ariane.render to see the magic happen:

<%= ariane.render %>

This will render the following:

<ul class="breadcrumb">
  <li>
    <a href="/">Home</a>
    <span class="divider">/</span>
  </li>
  <li class="active">Other</li>
</ul>

ariane.add

ariane.add takes two arguments, both being optional.

Note that if you don't set the url, the text will simply be rendered as is.

Alternatively, you can pass a block to ariane.add. The block will receive the new crumb as argument.

ariane.add do |crumb|
  crumb.text = 'Home'
  crumb.url  = root_path
end

Customize the output

Ariane provides a set of renderers you can use to generate the output. To see the options you can use with each renderer, take a look at the wiki.

The default renderer is HTMLList but you can select another one.

Using ariane.render

You can choose the renderer when calling ariane.render by passing it as the first argument:

<%= ariane.render(Ariane::Render::HTML) %>

This will render the following text:

<p class="breadcrumb">
  <a href="/">Home</a> / Other
</p>

Using an initializer

You may also choose to set the renderer when Rails is loaded:

# config/initializers/ariane.rb
Ariane.configure do |config|
  config.default_renderer = Ariane::Render::HTML
end

If you want further customization, you can instanciate the renderer and then use it in Ariane.configure.

# config/initializers/ariane.rb
rndr = Ariane::Render::HTML.new(divider: ' | ')

Ariane.configure do |config|
  config.default_renderer = rndr
end

Calling ariane.render will output the following HTML:

<p class="breadcrumb">
  <a href="/">Home</a> | Other
</p>

Bring your own Renderer

Ariane is flexible enough to let you define or extend renderers.

class HTMLOrderedList < Ariane::Render::HTMLList
  def list(crumbs)
    content_tag(:ol, class: options[:list_class]) do
      raw items(crumbs)
    end
  end

  def divider
    content_tag(:span, '|', class: 'separator')
  end
end

This example is simple but shows that you can touch pretty anything in the renderers.

Now if you call

<%= ariane.render(HTMLOrderedList) %>

You'll obtain the following HTML:

<ol class="breadcrumb">
  <li>
    <a href="/">Home</a>
    <span class="separator">|</span>
  </li>
  <li class="active">Other</li>
</ul>

Create a renderer from scratch

You can create a complete renderer, simply take a look at lib/ariane/render/html.rb for a complete example implementation.

I18n

Since Ariane is used in before filters or in the views, it supports I18n out of the box.

ariane.add t('home'), root_path