Project

hensel

0.0
No commit activity in last 3 years
No release in over 3 years
Hensel makes it easy to build the breadcrumbs.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

 Project Readme

Hensel

Build Status

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

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