easycrumbs

Easy breadcrumbs for your site

Installation

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"

Quick start

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

Model names

From database

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

From custom method

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

From i18n

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

Controller names

From controller name

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

From custom method

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

From i18n

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

Action prefixes

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

Default

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

Custom

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

From i18n

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

Blank links option

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

Rendering options

You can set some rendering options also:

Separator

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

Last element as hyperlink

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>

Custom collection

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

easycrumbs

Installation

Quick start

Model names

From database

From custom method

From i18n

Controller names

From controller name

From custom method

From i18n

Action prefixes

Default

Custom

From i18n

Blank links option

Rendering options

Separator

Last element as hyperlink

Custom collection

Copyright