easycrumbs¶ ↑

Easy breadcrumbs for your site

• gemcutter

• repository

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

Copyright¶ ↑

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