1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
---
redirect_from: /docs/documentation.html
---
# Arbre
HTML Views in Ruby
### Introduction
Arbre is a alternate template system for [Ruby on Rails Action View](http://guides.rubyonrails.org/action_view_overview.html).
Arbre expresses HTML using a Ruby DSL, which makes it similar to the [Builder](https://github.com/tenderlove/builder) gem for XML.
Arbre was extracted from [Active Admin](https://activeadmin.info/).
An example `index.html.arb`:
```ruby
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:
```ruby
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 with an HTML class corresponding to the component class name. This can be overridden by redefining the `tag_name` method.
Several examples of Arbre components are [included in Active Admin](https://activeadmin.info/12-arbre-components.html)
### Contexts
An [Arbre::Context](http://www.rubydoc.info/gems/arbre/Arbre/Context) is an object in which Arbre DSL is interpreted, providing a root for the Ruby DOM that can be [searched and manipulated](http://www.rubydoc.info/gems/arbre/Arbre/Element). 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.
```ruby
html = Arbre::Context.new do
panel "Hello World", id: "my-panel" do
span "Inside the panel"
text_node "Plain text"
end
end
puts html.to_s # =>
```
```html
<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](http://guides.rubyonrails.org/action_view_overview.html#overview-of-helpers-provided-by-action-view)
### Background
Similar projects include:
- [Markaby](http://markaby.github.io/), written by \_why the luck stiff.
- [Erector](http://erector.github.io/), developed at PivotalLabs.
- [Fortitude](https://github.com/ageweke/fortitude), developed at Scribd.
- [Inesita](https://inesita.fazibear.me/) (Opal)
- [html_builder](https://github.com/crystal-lang/html_builder) (Crystal)
|
