adam-pl / crummy

Tasty breadcrumbs! Crummy is a simple and tasty way to add breadcrumbs to your Rails applications.

Crummy

Crummy is a simple and tasty way to add breadcrumbs to your Rails applications.

Install

Simply add the dependency to your Gemfile:

gem "crummy", "~> 1.7.0"

Example

In your controllers you may add_crumb either like a before_filter or within a method (It is also available to views).

class ApplicationController
  add_crumb "Home", '/'
end

class BusinessController < ApplicationController
  add_crumb("Businesses") { |instance| instance.send :businesses_path }
  add_crumb("Comments", only: "comments") { |instance| instance.send :businesses_comments_path }
  before_filter :load_comment, only: "show"
  add_crumb :comment, only: "show"

  # Example for nested routes:
  add_crumb(:document) { [:account, :document] }

  def show
    add_crumb @business.display_name, @business
  end

  def load_comment
    @comment = Comment.find(params[:id])
  end
end

Then in your view:

<%= render_crumbs %>

Options for render_crumbs

render_crumbs renders the list of crumbs as either html or xml

It takes 3 options

The output format. Can either be :xml or :html or :html_list. Defaults to :html

format: (:html|:html_list|:xml)

The separator text. It does not assume you want spaces on either side so you must specify. Defaults to » for :html and <crumb> for :xml

separator: string

Render links in the output. Defaults to true

links: boolean

skip_if_blank: true

Render Richsnipet Default to false

microdata: true

With this option, output will be blank if there are no breadcrumbs.

Examples

render_crumbs                     #=> <a href="/">Home</a> &raquo; <a href="/businesses">Businesses</a>
render_crumbs separator: ' | '    #=> <a href="/">Home</a> | <a href="/businesses">Businesses</a>
render_crumbs format: :xml        #=> <crumb href="/">Home</crumb><crumb href="/businesses">Businesses</crumb>
render_crumbs format: :html_list  #=> <ul class="" id=""><li class=""><a href="/">Home</a></li><li class=""><a href="/">Businesses</a></li></ul>
render_crumbs format: :html_list, :microdata => true
                                  #=> <ul class="" id=""><li class="" itemscope="itemscope" itemtype="http://data-vocabulary.org/Breadcrumb">
                                  #     <a href="/" itemprop="url"><span itemprop="title">Home</span></a></li></ul>

A crumb with a nil argument for the link will output an unlinked crumb.

With format: :html_list you can specify additional params: :li_class, :ul_class, :ul_id

App-wide configuration

You have the option to pre-configure any of the Crummy options in an application-wide configuration. The options above are available to configure, with the exception of :separator, as well as many others.

The biggest difference is that :separator is not an option. Instead, you have format-specific configuration options: :html_separator, :xml_separator, and :html_list_separator. :separator can still be overridden in the view.

Insert the following in a file named config/initializers/crummy.rb:

Crummy.configure do |config|
  config.format = :xml
end

Possible parameters for configuration are:

:format
:links
:skip_if_blank
:html_separator
:xml_separator
:html_list_separator
:first_class
:last_class
:ul_id
:ul_class
:li_class
:microdata

See lib/crummy.rb for a list of these parameters and their defaults.

Live example application

An example application is available right inside this gem. That application is documented, see example/README for details about usage.

Todo

• Accept collections of models as a single argument
• Accept instances of models as a single argument
• Allow for variables in names. (The workaround is to do your own before_filter for that currently)
• Make a crumbs? type method

Credits

• Zach Inglis of Superhero Studios
• Andrew Nesbitt
• Rein Henrichs
• Les Hill
• Sandro Turriate
• Przemysław Kowalczyk
  • feature ideas
• Sharad Jain
• Max Riveiro
• Kamil K. Lemański
• Brian Cobb
• Kir Shatrov (Evrone company)
• sugilog
• Trond Arve Nordheim
• Jan Szumiec
• Jeff Browning
• Bill Turner

Copyright 2008-2013 Zach Inglis, released under the MIT license