= Erector
* http://erector.rubyforge.org
* mailto:[email protected]
== DESCRIPTION
Erector is a Builder-like view framework, inspired by Markaby but overcoming
some of its flaws. In Erector all views are objects, not template files,
which allows the full power of object-oriented programming (inheritance,
modular decomposition, encapsulation) in views.
== FEATURES/PROBLEMS:
While Erector is in use on several projects, it is still at a relatively
early stage. In particular, not all features are documented (although
the most important ones are).
== SYNOPSIS
require 'erector'
class Hello < Erector::Widget
def render
div do
text "Hello!"
end
end
end
== REQUIREMENTS
The gem depends on hoe and rake, although this is just for building
erector (those who just use erector won't need these).
== INSTALL
To install as a gem:
* sudo gem install erector
Then add "require 'erector'" to any files which need erector.
To install as a Rails plugin:
* Copy the erector source to vendor/plugins/erector in your Rails directory.
When installing this way, erector is automatically available to your Rails code
(no require directive is needed).
== LICENSE:
(The MIT License)
Copyright (c) 2007-8 Pivotal Labs
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
== MOTIVATION
Why use Erector? This section will soon become a real essay or blog post,
but briefly:
* Markaby-style DOM Domain language
* Your views are real classes, written in a real language, allowing
* Functional decomposition
* Inheritance
* Composition, not partials
* Well-defined semantics for variables, loops, blocks
* Dependency injection via constructor params
* As little magic as possible (e.g. no automagic copying of "assigns" variable from your controller)
* yield works again (Markaby broke it)
* Very testable
* form_for ERB code is craaaaazy (not to mention the quagmire of options vs. htmloptions)
* Output is streamed, improving performance over string copy
== USER DOCUMENTATION
The basic way to construct some HTML/XML with erector is to
subclass Erector::Widget and implement a render method:
class Hello < Erector::Widget
def render
html do
head do
title "Hello"
end
body do
text "Hello, "
b "world!"
end
end
end
end
Hello.new.to_s
#=> <html><head><title>Hello</title></head><body>Hello, <b>world!</b></body></html>
Here are the basics:
element('foo') # <foo></foo>
empty_element('foo') # <foo />
html # <html></html> (likewise for other common html tags)
b "foo" # <b>foo</b>
text 'foo' # foo
text '&<>' # &<> (what you generally want, especially
# if the text came from the user or a database)
text raw('&<>') # &<> (back door for raw html)
rawtext('&<>') # &<> (alias for text(raw()))
html { text foo } # <html>foo</html>
html "foo" # <html>foo</html>
html foo # <html>bar</html> (if the method foo returns the string "bar")
a(:href => 'foo.html') # <a href="foo.html"></a>
a(:href => 'q?a&b') # <a href="q?a&b"></a> (quotes as for text)
a(:href => raw('&')) # <a href="&"></a>
text nbsp("Save Doc") # Save Doc (turns spaces into non-breaking spaces)
instruct # <?xml version="1.0" encoding="UTF-8"?>
TODO: document more obscure features like capture, Table, :class => ['one', 'two']
=== Using Erector from Ruby on Rails
Your views are just ruby classes. Your controller instantiates the relevant view and calls render.
For example:
app/controllers/welcome_controller.rb:
class WelcomeController < ApplicationController
def index
render :template => 'welcome/show'
end
end
app/views/welcome/show.rb:
class Views::Welcome::Show < Erector::Widget
def render
html do
head do
title "Welcome page"
end
body do
p "Hello, world"
end
end
end
end
For Rails to find these .rb files during render, you must first either copy the erector source to
vendor/plugins/erector, or add `require 'erector'` to config/environment.rb. You also should delete (or rename)
any other view files with the same base name that might be getting in the way.
=== Erect
To make Rails integration as smooth as possible, we've written a little tool that will help you
erect your existing Rails app. The "erect" tool will convert HTML or HTML/ERB into an Erector class.
It ships as part of the Erector gem, so to try it out, install the gem, then run
erect app/views/foos/*.html.erb
or just
erect app/views
and then delete the original files when you're satisfied.
Here's a little command-line howto for erecting a scaffold Rails app:
rails foo
cd foo
script/generate scaffold post title:string body:text published:boolean
erect app/views/posts/*.erb
mate app/views/posts
sleep 30 # this should be enough time for you to stop drooling
rm app/views/posts/*.erb
(echo ""; echo "require 'erector'") >> config/environment.rb
rake db:migrate
script/server
open http://localhost:3000/posts
=== Layout Inheritance
Erector replaces the typical Rails layout mechanism with a more natural construct, the use of inheritance. Want a common
layout? Just implement a layout superclass and inherit from it. Implement render in the superclass and implement template
methods in its subclasses. There's one trick you'll need to use this layout for non-erector templates. Here's an example.
`application.rb` - The Erector layout superclass
class Views::Layouts::Application < Erector::Widget
attr_accessor :content
def render
html do
head { } # head content here
# body content here
body do
text content
end
end
end
end
`application.mab` - The markaby template (adjust for other appropriately templating technologies)
widget = Views::Layouts::Application.new(self)
widget.content = content_for_layout
self << widget.to_s
Here the abstract layout widget is used in a concrete fashion by the template-based layout. Normally, the `content` method
would be implemented by subclassing widgets, but the layout template sets it directly and then calls to_s on the layout widget.
This allows the same layout to be shared in a backward compatible way.
=== Other ways to call erector
Instead of subclassing Erector::Widget and implementing a render
method, you can pass a block to Erector::Widget.new. For example:
html = Erector::Widget.new do
p "Hello, world!"
end
html.to_s #=> <p>Hello, world!</p>
This lets you define mini-widgets on the fly.
== DEVELOPER NOTES
* Check out project from rubyforge:
svn co svn+ssh://[email protected]/var/svn/erector/trunk erector
* Install gems:
sudo gem install rake rails rspec rubyforge hpricot treetop
* Run specs:
rake
* Check out the available rake tasks:
rake -T
=== VERSIONING POLICY
* Versions are of the form major.minor.tiny
* Tiny revisions fix bugs or documentation
* Tiny revisions are roughly equal to the svn revision number when they were made
* Minor revisions add API calls, or change behavior
* Minor revisions may also remove API calls, but these must be clearly announced in History.txt, with instructions on how to migrate
* Major revisions are about marketing more than technical needs. We will stay in major version 0 until we're happy taking the "alpha" label off it. And if we ever do a major overhaul of the API, especially one that breaks backwards compatibility, we will probably want to increment the major version.
* We will not be shy about incrementing version numbers -- if we end up going to version 0.943.67454 then so be it.
* Developers should attempt to add lines in History.txt to reflect their checkins. These should reflect feature-level changes, not just one line per checkin. The top section of History.txt is used as the Release Notes by the "rake publish" task and will appear on the RubyForge file page.
* Someone making a release must fill in the version number in History.txt as well as in Rakefile. Note that "rake release" requires a "VERSION=1.2.3" parameter to confirm you're releasing the version you intend.
* As soon as a release is made and published, the publisher should go into History.txt and make a new section. Since we won't yet know what the next version will be called, the new section will be noted by a single "===" at the top of the file.
* http://erector.rubyforge.org
* mailto:[email protected]
== DESCRIPTION
Erector is a Builder-like view framework, inspired by Markaby but overcoming
some of its flaws. In Erector all views are objects, not template files,
which allows the full power of object-oriented programming (inheritance,
modular decomposition, encapsulation) in views.
== FEATURES/PROBLEMS:
While Erector is in use on several projects, it is still at a relatively
early stage. In particular, not all features are documented (although
the most important ones are).
== SYNOPSIS
require 'erector'
class Hello < Erector::Widget
def render
div do
text "Hello!"
end
end
end
== REQUIREMENTS
The gem depends on hoe and rake, although this is just for building
erector (those who just use erector won't need these).
== INSTALL
To install as a gem:
* sudo gem install erector
Then add "require 'erector'" to any files which need erector.
To install as a Rails plugin:
* Copy the erector source to vendor/plugins/erector in your Rails directory.
When installing this way, erector is automatically available to your Rails code
(no require directive is needed).
== LICENSE:
(The MIT License)
Copyright (c) 2007-8 Pivotal Labs
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
== MOTIVATION
Why use Erector? This section will soon become a real essay or blog post,
but briefly:
* Markaby-style DOM Domain language
* Your views are real classes, written in a real language, allowing
* Functional decomposition
* Inheritance
* Composition, not partials
* Well-defined semantics for variables, loops, blocks
* Dependency injection via constructor params
* As little magic as possible (e.g. no automagic copying of "assigns" variable from your controller)
* yield works again (Markaby broke it)
* Very testable
* form_for ERB code is craaaaazy (not to mention the quagmire of options vs. htmloptions)
* Output is streamed, improving performance over string copy
== USER DOCUMENTATION
The basic way to construct some HTML/XML with erector is to
subclass Erector::Widget and implement a render method:
class Hello < Erector::Widget
def render
html do
head do
title "Hello"
end
body do
text "Hello, "
b "world!"
end
end
end
end
Hello.new.to_s
#=> <html><head><title>Hello</title></head><body>Hello, <b>world!</b></body></html>
Here are the basics:
element('foo') # <foo></foo>
empty_element('foo') # <foo />
html # <html></html> (likewise for other common html tags)
b "foo" # <b>foo</b>
text 'foo' # foo
text '&<>' # &<> (what you generally want, especially
# if the text came from the user or a database)
text raw('&<>') # &<> (back door for raw html)
rawtext('&<>') # &<> (alias for text(raw()))
html { text foo } # <html>foo</html>
html "foo" # <html>foo</html>
html foo # <html>bar</html> (if the method foo returns the string "bar")
a(:href => 'foo.html') # <a href="foo.html"></a>
a(:href => 'q?a&b') # <a href="q?a&b"></a> (quotes as for text)
a(:href => raw('&')) # <a href="&"></a>
text nbsp("Save Doc") # Save Doc (turns spaces into non-breaking spaces)
instruct # <?xml version="1.0" encoding="UTF-8"?>
TODO: document more obscure features like capture, Table, :class => ['one', 'two']
=== Using Erector from Ruby on Rails
Your views are just ruby classes. Your controller instantiates the relevant view and calls render.
For example:
app/controllers/welcome_controller.rb:
class WelcomeController < ApplicationController
def index
render :template => 'welcome/show'
end
end
app/views/welcome/show.rb:
class Views::Welcome::Show < Erector::Widget
def render
html do
head do
title "Welcome page"
end
body do
p "Hello, world"
end
end
end
end
For Rails to find these .rb files during render, you must first either copy the erector source to
vendor/plugins/erector, or add `require 'erector'` to config/environment.rb. You also should delete (or rename)
any other view files with the same base name that might be getting in the way.
=== Erect
To make Rails integration as smooth as possible, we've written a little tool that will help you
erect your existing Rails app. The "erect" tool will convert HTML or HTML/ERB into an Erector class.
It ships as part of the Erector gem, so to try it out, install the gem, then run
erect app/views/foos/*.html.erb
or just
erect app/views
and then delete the original files when you're satisfied.
Here's a little command-line howto for erecting a scaffold Rails app:
rails foo
cd foo
script/generate scaffold post title:string body:text published:boolean
erect app/views/posts/*.erb
mate app/views/posts
sleep 30 # this should be enough time for you to stop drooling
rm app/views/posts/*.erb
(echo ""; echo "require 'erector'") >> config/environment.rb
rake db:migrate
script/server
open http://localhost:3000/posts
=== Layout Inheritance
Erector replaces the typical Rails layout mechanism with a more natural construct, the use of inheritance. Want a common
layout? Just implement a layout superclass and inherit from it. Implement render in the superclass and implement template
methods in its subclasses. There's one trick you'll need to use this layout for non-erector templates. Here's an example.
`application.rb` - The Erector layout superclass
class Views::Layouts::Application < Erector::Widget
attr_accessor :content
def render
html do
head { } # head content here
# body content here
body do
text content
end
end
end
end
`application.mab` - The markaby template (adjust for other appropriately templating technologies)
widget = Views::Layouts::Application.new(self)
widget.content = content_for_layout
self << widget.to_s
Here the abstract layout widget is used in a concrete fashion by the template-based layout. Normally, the `content` method
would be implemented by subclassing widgets, but the layout template sets it directly and then calls to_s on the layout widget.
This allows the same layout to be shared in a backward compatible way.
=== Other ways to call erector
Instead of subclassing Erector::Widget and implementing a render
method, you can pass a block to Erector::Widget.new. For example:
html = Erector::Widget.new do
p "Hello, world!"
end
html.to_s #=> <p>Hello, world!</p>
This lets you define mini-widgets on the fly.
== DEVELOPER NOTES
* Check out project from rubyforge:
svn co svn+ssh://[email protected]/var/svn/erector/trunk erector
* Install gems:
sudo gem install rake rails rspec rubyforge hpricot treetop
* Run specs:
rake
* Check out the available rake tasks:
rake -T
=== VERSIONING POLICY
* Versions are of the form major.minor.tiny
* Tiny revisions fix bugs or documentation
* Tiny revisions are roughly equal to the svn revision number when they were made
* Minor revisions add API calls, or change behavior
* Minor revisions may also remove API calls, but these must be clearly announced in History.txt, with instructions on how to migrate
* Major revisions are about marketing more than technical needs. We will stay in major version 0 until we're happy taking the "alpha" label off it. And if we ever do a major overhaul of the API, especially one that breaks backwards compatibility, we will probably want to increment the major version.
* We will not be shy about incrementing version numbers -- if we end up going to version 0.943.67454 then so be it.
* Developers should attempt to add lines in History.txt to reflect their checkins. These should reflect feature-level changes, not just one line per checkin. The top section of History.txt is used as the Release Notes by the "rake publish" task and will appear on the RubyForge file page.
* Someone making a release must fill in the version number in History.txt as well as in Rakefile. Note that "rake release" requires a "VERSION=1.2.3" parameter to confirm you're releasing the version you intend.
* As soon as a release is made and published, the publisher should go into History.txt and make a new section. Since we won't yet know what the next version will be called, the new section will be noted by a single "===" at the top of the file.