Arbre

HTML Views in Ruby

Introduction

Arbre is a alternate template system for Ruby on Rails Action View. Arbre expresses HTML using a Ruby DSL, which makes it similar to the Builder gem for XML. Arbre was extracted from Active Admin.

An example index.html.arb:

html {
  head {
    title "Welcome page"
  }
  body {
    para "Hello, world"
  }
}

The purpose of Arbre is to leave the view as Ruby objects as long as possible, which allows an object-oriented approach including inheritance, composition, and encapsulation.

Installation

Add gem arbre to your Gemfile and bundle install.

Arbre registers itself as a Rails template handler for files with an extension .arb.

Tags

Arbre DSL is composed of HTML tags. Tag attributes including id and HTML classes are passed as a hash parameter and the tag body is passed as a block. Most HTML5 tags are implemented, including script, embed and video.

A special case is the paragraph tag, <p>, which is mapped to para.

JavaScript can be included by using script { raw ... }

To include text that is not immediately part of a tag use text_node.

Components

Arbre DSL can be extended by defining new tags composed of other, simpler tags. This provides a simpler alternative to nesting partials. The recommended approach is to subclass Arbre::Component and implement a new builder method.

The builder_method defines the method that will be called to build this component when using the DSL. The arguments passed into the builder_method will be passed into the #build method for you.

For example:

class Panel < Arbre::Component
  builder_method :panel

  def build(title, attributes = {})
    super(attributes)

    h3(title, class: "panel-title")
  end
end

By default, components are div tags. This can be overridden by redefining the tag_name method.

Several examples of Arbre components are included in Active Admin

Contexts

An Arbre::Context is an object in which Arbre DSL is interpreted, providing a root for the Ruby DOM that can be searched and manipulated. A context is automatically provided when a .arb template or partial is loaded. Contexts can be used when developing or testing a component. Contexts are rendered by calling to_s.

html = Arbre::Context.new do
  panel "Hello World", class: "panel", id: "my-panel" do
    span "Inside the panel"
    text_node "Plain text"
  end
end

puts html.to_s # =>

<div class='panel' id="my-panel">
  <h3 class='panel-title'>Hello World</h3>
  <span>Inside the panel</span>
  Plain text
</div>

A context allows you to specify Rails template assigns, aka. ‘locals’ and helper methods. Templates loaded by Action View have access to all Action View helper methods

Background

Similar projects include:

• Markaby, written by _why the luck stiff.
• Erector, developed at PivotalLabs.
• Fortitude, developed at Scribd.
• Inesita (Opal)
• html_builder (Crystal)