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 (#collectioncollection.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

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

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 Actors > 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 (c) 2010 Stanisław Kolarzowski. See LICENSE for details.