h1. Crummy

h2. Introduction

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

h2. Install

Simply add the dependency to your Gemfile:

<pre>
  <code>
    gem "crummy", "~> 1.5.0"
  </code>
</pre>

h3. Rails 2

In your terminal, write:

<pre>
  <code>
    gem install crummy
  </code>
</pre>

h2. Example

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

<pre>
  <code>
    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
  </code>
</pre>

Then in your view:

<pre>
  <code>
    <%= render_crumbs %>
  </code>
</pre>

h2. 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

<code>:format => (:html|:html_list|:xml)</code>

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

<code>:separator => string</code>

Render links in the output. Defaults to +true+

<code>:links => boolean</code>

<code>:skip_if_blank => true</code>

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

h3. Examples

<pre>
 <code>
  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>
 </code>
</pre>
A crumb with a nil argument for the link will output an unlinked crumb.

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

h3. 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@:

<pre>
  <code>
    Crummy.configure do |config|
      config.format = :xml
    end
  </code>
</pre>

Possible parameters for configuration are: 

<pre>
  <code>
    :format
    :links
    :skip_if_blank
    :html_separator
    :xml_separator
    :html_list_separator
    :first_class
    :last_class
    :ul_id
    :ul_class
    :li_class
    :active_li_class
  </code>
</pre>

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

h2. Notes

Test library is at "Crummy Test":https://github.com/zachinglis/crummy-test

h2. 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

h2. Credits

* "Zach Inglis":http://zachinglis.com of "London Made":http://londonmade.co.uk
* "Rein Henrichs":http://reinh.com
* "Les Hill":http://blog.leshill.org/
* "Sandro Turriate":http://turriate.com/
* "Przemysław Kowalczyk":http://szeryf.wordpress.com/2008/06/13/easy-and-flexible-breadcrumbs-for-rails/ - feature ideas
* "Sharad Jain":http://github.com/sjain
* "Max Riveiro":http://github.com/kavu
* "Kamil K. Lemański":http://kml.jogger.pl
* "Brian Cobb":http://bcobb.net/
* "Kir Shatrov":http://github.com/shatrov ("Evrone company":http://evrone.com)
* "sugilog":http://github.com/sugilog
* "Trond Arve Nordheim":http://github.com/tanordheim
* "Jan Szumiec":http://github.com/jasiek
* "Jeff Browning":http://github.com/jbrowning
* "Bill Turner":http://github.com/billturner

*Copyright (c) 2008-2011 Zach Inglis, released under the MIT license*