Hensel

Hensel makes it easy to build the breadcrumbs.

Especially, want to recommend for use in Sinatra and Padrino.

Installation

Add this line to your application's Gemfile:

gem 'hensel'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hensel

Requirements

MRI 2.0+

Overview

Hensel can be used easily in your web applications, and it has powerful flexibility. You can use it as helper and builder. In the next section, will explain in detail how to use them.

Usage

Configuration

require 'hensel'
    
Hensel.configure do |config|
  # Default values
  config.bootstrap            = false
  config.escape_html          = true
  config.indentation          = true
  config.last_item_link       = false
  config.richsnippet          = :microdata
  config.attr_wrapper         = "'"
  config.whitespace           = "  "
  config.parent_element       = :ul
  config.before_load          = nil
  config.default_item_options = {}
  config.parent_attributes    = {}
end

If bootstrap is set to true, the parent element of breadcrumbs will contain breadcrumb as class attrbiute, and the last item will contain active as class attrbiute as well. It will be something like below.

<ul class='breadcrumb'>
  <li>
    <a href='/'>
      index
    </a>
  </li>
  <li class='active'>
    current
  </li>
</ul>

If escape_html is set to true, the text of item and all value of attributes will be escaped.

If indentation is set to true, the breadcrumbs will be indented.

If richsnippet is set to correct symbol, the breadcrumbs will follow the rules of the rich snippets that have been specified. There is a :microdata and :rdfa, please specify nil if not required type. It will be something like below.

<!-- microdata -->
<ul>
  <li itemscope itemtype='http://data-vocabulary.org/Breadcrumb'>
    <a href='/' itemprop='url'>
      <span itemprop='title'>
        index
      </span>
    </a>
  </li>
  <li itemscope itemtype='http://data-vocabulary.org/Breadcrumb'>
    <span itemprop='title'>
      current
    </span>
  </li>
</ul>

<!-- RDFa -->
<ul xmlns:v='http://rdf.data-vocabulary.org/#'>
  <li typeof='v:Breadcrumb'>
    <a href='/' rel='v:url' property="v:title">
      index
    </a>
  </li>
  <li typeof='v:Breadcrumb'>
    <span property="v:title">
      current
    </span>
  </li>
</ul>

If don't have special reason, you should enable the option. Microdata and RDFa are supported by google.

If last_item_link is set to true, the link of the last item will contain a element as with other elements. It will be something below.

<!-- If `last_item_link` is set to `true` -->
<ul class="breadcrumb">
  <li>
    <a href="/">
      index
    </a>
  </li>
  <li>
    <a href="/foo">
      foo
    </a>
  </li>
</ul>
<!-- If `last_item_link` is set to `false` -->
<ul class="breadcrumb">
  <li>
    <a href="/">
      index
    </a>
  </li>
  <li>
    <span>
      foo
    </span>
  </li>
</ul>

If attr_wrapper is set to a wrapper string, all attributes will be used it as the attribute wrapper. It will be somthing below.

<!-- If `attr_wrapper` is set to `'"'` -->
<ul class="breadcrumb">
  <li>
    <a href="/">
      index
    </a>
  </li>
</ul>
<!-- If `attr_wrapper` is set to `nil` -->
<ul class=breadcrumb>
  <li>
    <a href=/>
      index
    </a>
  </li>
</ul>

If whitespace is set to a whitespace string, all indentation will be used it as the indentation space. It will be somthing below.

<!-- If `whitespace` is set to `" "` -->
<ul>
 <li>
  <a href="/">
   index
  </a>
 </li>
</ul>
<!-- If `attr_wrapper` is set to `"    "` -->
<ul>
    <li>
        <a href="/">
            index
        </a>
    </li>
</ul>

If parent_element is set to a name string, it will be used as a name of the parent element.

If before_load is set to Proc, it will be evaluated within the context of Hensel::Builder. It will be something below.

Hensel.configuration.before_load = proc { add("Home", "/") }
builder = Hensel::Builder.new
home = builder.items.first
home.text #=> "Home"
home.url #=> "/"

**If Hash is set to default_item_options, all items will use it as options.

Hensel.configuration.default_item_options = { class: "tested" }
builder = Hensel::Builder.new
builder.add("Home", "/")
builder.items.first.render #=> "<li class='tested'><a href='/'>Home</a></li>"

**If Hash is set to parent_attributes, the parent element will include it as attributes.

Hensel.configuration.parent_attributes = { class: "parent-tested" }
builder = Hensel::Builder.new
builder.render #=> "<ul class='parent-tested'></ul>"

Builder

`add(text, url, **options) -> Hensel::Builder::Item`

Adds a new item to items, and returns a fresh instance of Hensel::Builder::Item built by the builder.

builder = Hensel::Builder.new
item = builder.add("home", "/")
item.text #=> "home"
item.url #=> "/"

`add(**parameters) -> Hensel::Builder::Item`

builder = Hensel::Builder.new
item = builder.add(text: "home", url: "/")
item.text #=> "home"
item.url #=> "/"

`remove(text)`

Removes the item from items.

builder = Hensel::Builder.new
builder.add(text: "home", url: "/")

builder.items.empty? #=> false
builder.remove("home")
builder.items.empty? #=> true

`remove{|item| ... }`

builder = Hensel::Builder.new
builder.add(text: "home", url: "/")

builder.items.empty? #=> false
builder.remove{|item| item.text == "home" }
builder.items.empty? #=> true

`render -> String`

Renders the breadcrumbs, and returns the html of breadcrumbs rendered by this method.

builder = Hensel::Builder.new
builder.add(text: "home", url: "/")

builder.render #=> "<ul> ... </ul>"

`render{ ... } -> String`

This method is for customize breadcrumbs.

If this method has a parameter, it will be an instance of Hensel::Builder::Item.

If this method does not have parameter, the block will be evaluated as an instance of Hensel::Builder::Item.

However, if you use render with block, a few configuration(richsnippets, last_item_link) will be ignored.

builder = Hensel::Builder.new
builder.add(text: "home", url: "/")

builder.render {|item| "<li>#{item.text}</li>" } #=> "<ul><li>home</li></ul>"
builder.render do
  if last?
    node(:li) do
      node(:span){ item.text }
    end
  else
    node(:li) do
      node(:a, href: item.url) do
        node(:span){ item.text }
      end
    end
  end
end

Helpers

The helper can be used in your web application.

Basic

include Hensel::Helpers

with Sinatra

class Sample < Sinatra::Base
  helpers Hensel::Helpers

  configure do
    Hensel.configure do |config|
      config.attr_wrapper = '"'
      config.whitespace   = '  '
    end
  end

  get "/" do
    breadcrumbs.add("home", "/")
    breadcrumbs.render
  end
end

with Padrino

# config/boot.rb
Padrino.before_load do
  Hensel.configure do |config|
    config.attr_wrapper = '"'
    config.whitespace   = '  '
  end
end

class Sample < Padrino::Application
  helpers Hensel::Helpers

  get :index do
    breadcrumbs.add("home", ?/)
    breadcrumbs.render
  end
end

Sinatra/Padrino Helpers

If you want to customize more, you should use SinatraHelpers. It can be used both in Sinatra and in Padrino.

class Sample < Sinatra::Base
  helpers Hensel::Helpers::SinatraHelpers
  set :hensel, builder_options: { class: "this-is-parent-class-name" },
               renderer: proc { node(:custom_element_name){ item.text }}

  configure do
    Hensel.configure do |config|
      config.attr_wrapper = '"'
      config.whitespace   = '  '
    end
  end

  get "/" do
    breadcrumbs.add("home", "/")
    breadcrumbs.render
  end
end

TODO

Support Rails
New syntax for Sinatra and Padrino

Contributing

Fork it ( https://github.com/namusyaka/hensel/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

hensel

Development