easycrumbs¶ ↑

Easy breadcrumbs for your site

• gemcutter

• repository

If you don’t have the Gemcutter sources yet:

gem sources -a http://gemcutter.org

To install the gem type:

gem install easycrumbs

Add it to your Gemfile

gem "easycrumbs"

It is really easy to have breadcrumbs in your project. Just type this into any view file and breadcrumbs will work for you.

breadcrumbs

ERB example:

<div id=breadcrumbs>
  <%= breadcrumbs %>
</div>

HAML example:

#breadcrumbs
  = breadcrumbs

You do not need to specify any more options in models or controllers. Easycrumbs will take everything it needs from your routes.rb file.

The routes.rb file with

map.resources :countries do |country|
  country.resources :movies do |movie|
    movie.resources :actors
  end
end

could generate this breadcrumb

Home > Countries > Country > Movies > Movie > Actors > Edit Actor

If your model has breadcrumb column in database then it will be used to generate breadcrumbs

@usa = Country.new(:breadcrumb => "Usa")
@titanic = Movie.new(:breadcrumb => "Titanic")
@leo = Actor.new(:breadcumb => "Leonardo Di Caprio")

Home > Countries > Usa > Movies > Titanic > Actors > Edit Leonardo Di Caprio

You can change column name using :name_column option

breadcrumbs :name_column => :seo

@usa = Country.new(:seo => "Usa")
@titanic = Movie.new(:seo => "Titanic")
@leo = Actor.new(:seo => "Leonardo Di Caprio")

Home > Countries > Usa > Movies > Titanic > Actors > Edit Leonardo Di Caprio

If you need custom name then just create method named breadcrumb in your model

class Actor < ActiveRecord::Base
  def breadcrumb
    "the best male actor: " + first_name
  end
end

Home > Countries > Usa > Movies > Titanic > Actors > Edit the best male actor: Leonardo

Easycrumbs fully support i18n

breadcrumbs :i18n => true

Name will be taken from this key if your model does not have breadcrumb column or method:

breadcrumbs.models.model_name

Example en.yml

en:
    breadcrumbs:
        models:
            country: C0untry
            movie: M0v13
            actor: 4ct0r

Home > Countries > C0untry > Movies > M0v13 > Actors > Edit 4act0r

Default behavior is to use controller name

class CountriesController < ApplicationController
class MoviesController < ApplicationController
class ActorsController < ApplicationController

Home > Countries > Usa > Movies > Titanic > Actors > Edit Leonardo Di Caprio

Similar to models you can specify custom breadcrumb method

class MoviesController < ApplicationController
  def breadcrumb
    "Movies (#{collection.size})"
  end
end

Home > Countries > Usa > Movies (234) > Titanic > Actors > Edit Leonardo Di Caprio

Controller can also use i18n names

breadcrumbs :i18n => true

Name will be taken from this key if your controller does not have breadcrumb method:

breadcrumbs.controllers.controller_name

Example en.yml

en:
    breadcrumbs:
      controllers:
          application: H0m3
          countries: C0untr135
          movies: M0v135
          actors: 4ct0r5

H0m3 > C0untr135 > Usa > M0v135 > Titanic > 4ct0r5 > Edit Leonardo Di Caprio

For last element you can add current action name as prefix. Example with Editing actor object:

Home > Countries > Usa > Movies > Titanic > Actors > Edit Leonardo Di Caprio

For default prefix is added only for new and edit actions.

Home > Countries > Usa > Movies > Titanic > Actors > Edit Leonardo Di Caprio
Home > Countries > Usa > Movies > Titanic > Actors > New Leonardo Di Caprio

You can change this behavior. Just set :prefix option as you want:

• :every - prefix will be added for every action

  breadcrumbs :prefix => :every
  action show => Actors > Show Leonardo Di Caprio
  action new  => Actors > New Leonardo Di Caprio
  action edit => Actors > Edit Leonardo Di Caprio

• :none - prefix will not be added to any action

  breadcrumbs :prefix => :none
  action show => Actors > Leonardo Di Caprio
  action new  => Actors > Leonardo Di Caprio
  action edit => Actors > Leonardo Di Caprio

• array of action names - prefix will be added only for specified actions

  breadcrumbs :prefix => [:show, :new]
  action show => Actors > Show Leonardo Di Caprio
  action new  => Actors > New Leonardo Di Caprio
  action edit => Actors > Leonardo Di Caprio

Action names can also be taken from i18n

breadcrumbs :i18n => true

Name will be taken from this key:

breadcrumbs.actions.action_name

Example en.yml

en:
    breadcrumbs:
      actions:
          new: N3w {{name}}
          edit: 3d1t {{name}}
          show: {{name}} 5h0w

When path will not be recognized then exception will be raised

EasyCrumbs::NoPath

If you would like to have blank link(just text, without hyperlink) instead then just set :blank_links option

breadcrumbs :blank_links => true

You can set some rendering options also:

Default breadcrumbs separator is set to “ > ”, but you can use something else if you want

breadcrumbs :separator => ' ==> '
Home ==> Countries ==> Usa ==> Movies ==> Titanic ==> Actors ==> Edit Leonardo Di Caprio

breadcrumbs :separator => '/'
Home/Countries/Usa/Movies/Titanic/Actors/Edit Leonardo Di Caprio

By default last element will always be render as hyperlink. If you would like to render it in plain text then use :last_link option

breadcrumbs :last_link => false
<a href="/actors"/>Actors</a> > Edit Leonardo Di Caprio

breadcrumbs :last_link => true
<a href="/actors"/>Actors</a> > <a href="/actors/1/edit">Edit Leonardo Di Caprio</a>

If you do not like idea that breadcrumbs are recognized using routes.rb file then you can write your own breadcrumbs generator. Create new class inherited from EasyCrumbs::Collection or just monkey patch initialize method from EasyCrumbs::Collection

Look at example for acts_as_tree gem

class EasyCrumbs::Collection
  def initialize(request, options = {})
    object = options[:object]
    collection = []
    path = {:action => 'show', :controller => 'people'}

    while(!object.nil?)
      collection << Breadcrumb.new(object, options.merge(:path => path.merge(:id => object.id)))
      object = object.parent
    end
    @breadcrumbs = collection.reverse
  end
end

• you will get request object and options hash from view helper(look at lib/easycrumbs/view_helpers.rb for more details)

• you have to set @breadcrumbs as collection of EasyCrumbs::Breadcrumb objects

• remember to pass options hash to every EasyCrumbs::Breadcrumb object

• path have to be a hash and has to be recognized by rails routing system

For objects:

grandfather = Person.create, :breadcrumb => "Grandfather"
father = Person.create :parent => grandfather, :breadcrumb => "Father"
son = Person.create :parent => father, :breadcrumb => "Son"

The code:

breadcrumbs, :last_link => false

will generate this:

<a href="/people/1">Grandfather</a> > <a href="/people/2">Father</a> > Son

Look at code at tests for more details

Copyright © 2010 Stanisław Kolarzowski. See LICENSE for details.