Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Easy breadcrumbs for your website
Ruby
branch: rails3

This branch is 7 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
.document
.gitignore
Gemfile
Gemfile.lock
LICENSE
README.rdoc
Rakefile
VERSION
easycrumbs.gemspec

README.rdoc

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

Copyright

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

Something went wrong with that request. Please try again.