Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
How did these breadcrumbs in your Rails application? Oh right, with this plugin!
Ruby
branch: master

This branch is 2 commits ahead, 2 commits behind roidrage:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app/helpers
lib
rails
spec
.gitignore
README.md
Rakefile
VERSION

README.md

Modifications from original Crumble

Call Breadcrumb.configure multiple time in many places in your Rails app.

Say, in your initializer file you have

Breadcrumb.configure do
  crumb :root, 'Main', :main_path
  ...
end

And you need this to be dynamic by changing or adding somwhere else in the app, just do

Braedcrumb.configure do
  # whatever changes or additions
  # you can also use what was defined in other places
  trail :foo, :bar, [:root, :foos]
end

The crumbs application helper method can also accept options:

:delimiter - in addition to specifying the default delimiter in the init file, you can change it on the fly with this option.
:link - default as true, which operates as normal. set false if you dont want the breadcrumbs to link at all (just a reference)
:exclude_first - dont even include the first crumb (usually main menu / root)

Those helped me include the crumb in the title: <%= crumbs :delimiter => ' > ', :link => false, :exclude_first => true %>

Thanks to the original crumble! see the repo here on github.

Installation

The gem is hosted on gemcutter, so if you haven’t already, add it as a gem source:

gem sources -a http://gemcutter.org/

Then install the Formtastic gem (recommended):

gem install crumble

Alternatively you can also install it as a Rails plugin:

script/plugin install git://github.com/mattmatt/crumble.git

Requires Rails 2.3.

Note: If you have configured Rails to reload all plugins in development mode, then putting your breadcrumbs configuration into an initializer won't work, since the classes, and therefore the breadcrumbs configuration will be unloaded after the request, and not be reloaded before the next one.

This will cause the problem. Either disable it, or let Rails use the default, which is to not reload plugins.

config.reload_plugins = true

Usage

I wanted to have a rather simple API to configure breadcrumbs, so I made one. Basically you configure your breadcrumbs in an initializers, e.g. config/initializers/breadcrumbs.rb like so:

Breadcrumb.configure do
  # Specify name, link title and the URL to link to
  crumb :profile, "Your Profile", :account_url
  crumb :root, "Home", :root_url

  # Specify controller, action, and an array of the crumbs you specified above
  trail :accounts, :show, [:root, :profile]
  trail :home, :index, [:root]

  # Specify the delimiter for the crumbs
  delimit_with "/"
end

You can hand over parameters to the URL generator methods, the parameters are expected to exist as instance variables in your controller/helper:

crumb :blog_comment, "Your Profile", :blog_comment_url, :blog, :comment

If you need to fetch a nested object from an existing one, you can do it with nested hashes, nesting knowing now boundaries, as long as a tree of objects conforming to them (in this case @user.blog.name) exists:

crumb :blog, "Your Blog", :blog_url, :user => {:blog => :name}
crumb :blog, "Your Blog", :blog_url, :user => :blog

If you really need to (only if you really, really need to), you can specify a string to be eval'd at runtime as parameter for the URL method. Brace yourself, it's not pretty:

crumb :blog, "Your Blog", :blog_url, '@user.blog'

You can also add URL parameters derived from the parameters of the current request:

crumb :search, "Search", :new_search_url, :params => :q

Arrays of parameters work too:

crumb :search, "Search", :new_search_url, :params => [:q, :country]

And nested parameters:

crumb :search, "Search", :new_search_url, :params => {:search => :q}

If you want to make the link title content dynamic, just use single quotes and rely on interpolation, you just need to ensure the interpolated code exists in the context of your helpers:

crumb :search, 'Search (Keywords: #{params[:q]})', :new_search_url, :params => :q

If you don't want to specify any URL method at all, just use :current, it'll just use all the parameters of the current action, of course being aware that you can't have an URL method called current to rely on. But who would do that anyway?

crumb :search, 'Search (Keywords: #{params[:q]})', :current

Internationalization usage

For example, if you want to localize your menu, define a new breadcrumbs node in your .yml file with all the keys for your elements. # config/locales/en.yml en: breadcrumbs: homepage: Homepage profile: Your Profile profile_dynamic: Hi {{name}}

# config/locales/es.yml
es:
  breadcrumbs:
    homepage: Homepage
    profile: Tu perfil
    profile_dynamic: Hola {{name}}

Then you can define the title of your crum as:

 crumb :profile, nil, :account_url

Crumble find your locale for the scope "breadcrumbs.#{crumb.name}"

If you want to make the I18n title content dynamic, just use a hash with the same key as the i18n param and with a hash value that will be interpolate to @user.name in this case:

  crumb :profile_dynamic, {:name => {:user => :name}}, :account_url

You can base trails on conditions using :unless and :if. Both need to point to a method that exists in the context of the view.

trail :home, :index, [:root], :unless => :logged_in?
trail :home, :index, [:your_account], :if => :logged_in?

Alternatively you can specify a block that takes the controller as an argument.

trail :home, :index, [:your_account], :if => lambda {|controller| controller.logged_in?}

Your trails can also relate to a bunch of actions, just specify an array instead.

trail :profiles, [:show, :edit], [:profile]

To keep your breadcrumbs definition neat and tidy, wrap them based on their context with a handy method called, you guessed it, context:

context "user profile" do
  trail :home, :index, [:root], :unless => :logged_in?
  trail :home, :index, [:your_account], :if => :logged_in?
end

Dump your trails and crumbs in there and bask in the glory of an easier readable crumbs definition.

If you don't want to have the last crumb linked, no problem at all, we can do that too:

Breadcrumb.configure do
  dont_link_last_crumb
end

Yep, that's it. Include that in your breadcrumbs definition and you're done. Then, in your views, just insert the following:

<%= crumbs %>

Don't forget to include the helper in the affected controllers:

class ApplicationController < ActionController::Base
    helper :breadcrumbs
end

If your trails reference non-existing crumbs, the plugin will raise an error telling you where in your configuration the illegal reference was made.

Future

If you think something's missing, let me know at meyer@paperplanes.de, or even better, send patches, including tests.

Contributors

  • Paco Guzmán (i18n support)

License

MIT

(c) 2009 Mathias Meyer

Something went wrong with that request. Please try again.