arbre 1.0.0.rc4 → 1.2.1

data/docs/index.md

@@ -0,0 +1,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)
+