Class: ERB
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Inherits: | Object |
Defined in: | lib/erb.rb, lib/erb.rb, lib/erb.rb, lib/erb.rb, lib/erb.rb |
Overview
ERB – Ruby Templating
Introduction
ERB
provides an easy to use but powerful templating system for Ruby. Using ERB
, actual Ruby code can be added to any plain text document for the purposes of generating document information details and/or flow control.
A very simple example is this:
require 'erb'
x = 42
template = ERB.new <<-EOF
The value of x is: <%= x %>
EOF
puts template.result(binding)
Prints: The value of x is: 42
More complex examples are given below.
Recognized Tags
ERB
recognizes certain tags in the provided template and converts them based on the rules below:
<% Ruby code -- inline with output %>
<%= Ruby expression -- replace with result %>
<%# comment -- ignored -- useful in testing %>
% a line of Ruby code -- treated as <% line %> (optional -- see ERB.new)
%% replaced with % if first thing on a line and % processing is used
<%% or %%> -- replace with <% or %> respectively
All other text is passed through ERB
filtering unchanged.
Options
There are several settings you can change when you use ERB
:
-
the nature of the tags that are recognized;
-
the value of
$SAFE
under which the template is run; -
the binding used to resolve local variables in the template.
See the .new and #result methods for more detail.
Character encodings
ERB
(or Ruby code generated by ERB
) returns a string in the same character encoding as the input string. When the input string has a magic comment, however, it returns a string in the encoding specified by the magic comment.
# -*- coding: utf-8 -*-
require 'erb'
template = ERB.new <<EOF
<%#-*- coding: Big5 -*-%>
\_\_ENCODING\_\_ is <%= \_\_ENCODING\_\_ %>.
EOF
puts template.result
Prints: _ENCODING_ is Big5.
Examples
Plain Text
ERB
is useful for any generic templating situation. Note that in this example, we use the convenient “% at start of line” tag, and we quote the template literally with %q{...}
to avoid trouble with the backslash.
require "erb"
# Create template.
template = %q{
From: James Edward Gray II <james@grayproductions.net>
To: <%= to %>
Subject: Addressing Needs
<%= to[/\w+/] %>:
Just wanted to send a quick note assuring that your needs are being
addressed.
I want you to know that my team will keep working on the issues,
especially:
<%# ignore numerous minor requests -- focus on priorities %>
% priorities.each do |priority|
* <%= priority %>
% end
Thanks for your patience.
James Edward Gray II
}.gsub(/^ /, '')
= ERB.new(template, 0, "%<>")
# Set up template data.
to = "Community Spokesman <spokesman@ruby_community.org>"
priorities = [ "Run Ruby Quiz",
"Document Modules",
"Answer Questions on Ruby Talk" ]
# Produce result.
email = .result
puts email
Generates:
From: James Edward Gray II <james@grayproductions.net>
To: Community Spokesman <spokesman@ruby_community.org>
Subject: Addressing Needs
Community:
Just wanted to send a quick note assuring that your needs are being addressed.
I want you to know that my team will keep working on the issues, especially:
* Run Ruby Quiz
* Document Modules
* Answer Questions on Ruby Talk
Thanks for your patience.
James Edward Gray II
Ruby in HTML
ERB
is often used in .rhtml
files (HTML with embedded Ruby). Notice the need in this example to provide a special binding when the template is run, so that the instance variables in the Product object can be resolved.
require "erb"
# Build template data class.
class Product
def initialize( code, name, desc, cost )
@code = code
@name = name
@desc = desc
@cost = cost
@features = [ ]
end
def add_feature( feature )
@features << feature
end
# Support templating of member data.
def get_binding
binding
end
# ...
end
# Create template.
template = %{
<html>
<head><title>Ruby Toys -- <%= @name %></title></head>
<body>
<h1><%= @name %> (<%= @code %>)</h1>
<p><%= @desc %></p>
<ul>
<% @features.each do |f| %>
<li><b><%= f %></b></li>
<% end %>
</ul>
<p>
<% if @cost < 10 %>
<b>Only <%= @cost %>!!!</b>
<% else %>
Call for a price, today!
<% end %>
</p>
</body>
</html>
}.gsub(/^ /, '')
rhtml = ERB.new(template)
# Set up template data.
toy = Product.new( "TZ-1002",
"Rubysapien",
"Geek's Best Friend! Responds to Ruby commands...",
999.95 )
toy.add_feature("Listens for verbal commands in the Ruby language!")
toy.add_feature("Ignores Perl, Java, and all C variants.")
toy.add_feature("Karate-Chop Action!!!")
toy.add_feature("Matz signature on left leg.")
toy.add_feature("Gem studded eyes... Rubies, of course!")
# Produce result.
rhtml.run(toy.get_binding)
Generates (some blank lines removed):
<html>
<head><title>Ruby Toys -- Rubysapien</title></head>
<body>
<h1>Rubysapien (TZ-1002)</h1>
<p>Geek's Best Friend! Responds to Ruby commands...</p>
<ul>
<li><b>Listens for verbal commands in the Ruby language!</b></li>
<li><b>Ignores Perl, Java, and all C variants.</b></li>
<li><b>Karate-Chop Action!!!</b></li>
<li><b>Matz signature on left leg.</b></li>
<li><b>Gem studded eyes... Rubies, of course!</b></li>
</ul>
<p>
Call for a price, today!
</p>
</body>
</html>
Notes
There are a variety of templating solutions available in various Ruby projects:
-
ERB's big brother, eRuby, works the same but is written in C for speed;
-
Amrita (smart at producing HTML/XML);
-
cs/Template (written in C for speed);
-
RDoc, distributed with Ruby, uses its own template engine, which can be reused elsewhere;
-
and others; search / RubyGems.org or / The Ruby Toolbox.
Rails, the web application framework, uses ERB
to create views.
Class Method Summary
-
.new(str, safe_level = nil, trim_mode = nil, eoutvar = '_erbout') ⇒ ERB
constructor
Constructs a new
ERB
object with the template specified in str. -
.version
Returns revision information for the erb.rb module.
Instance Attribute Summary
Instance Method Summary
-
#def_class(superklass = Object, methodname = 'result')
Define unnamed class which has methodname as instance method, and return it.
-
#def_method(mod, methodname, fname = '(ERB)')
Define methodname as instance method of mod from compiled Ruby source.
-
#def_module(methodname = 'erb')
Create unnamed module, define methodname as instance method of it, and return it.
- #location=(filename, lineno)
-
#make_compiler(trim_mode)
Creates a new compiler for
ERB
. -
#result(b = new_toplevel)
Executes the generated
ERB
code to produce a completed template, returning the results of that code. -
#run(b = new_toplevel)
Generate results and print them.
-
#set_eoutvar(compiler, eoutvar = '_erbout')
Can be used to set eoutvar as described in .new.
-
#new_toplevel
private
Returns a new binding each time near TOPLEVEL_BINDING for runs that do not specify a binding.
Constructor Details
.new(str, safe_level = nil, trim_mode = nil, eoutvar = '_erbout') ⇒ ERB
Constructs a new ERB
object with the template specified in str.
An ERB object works by building a chunk of Ruby code that will output the completed template when run. If safe_level is set to a non-nil value, ERB
code will be run in a separate thread with $SAFE set to the provided level.
If trim_mode is passed a String containing one or more of the following modifiers, ERB
will adjust its code generation as listed:
% enables Ruby code processing for lines beginning with %
<> omit newline for lines starting with <% and ending in %>
> omit newline for lines ending in %>
- omit blank lines ending in -%>
eoutvar can be used to set the name of the variable ERB
will build up its output in. This is useful when you need to run multiple ERB
templates through the same binding and/or when you want to control where output ends up. Pass the name of the variable to be used inside a String.
Example
require "erb"
# build data class
class Listings
PRODUCT = { :name => "Chicken Fried Steak",
:desc => "A well messages pattie, breaded and fried.",
:cost => 9.95 }
attr_reader :product, :price
def initialize( product = "", price = "" )
@product = product
@price = price
end
def build
b = binding
# create and run templates, filling member data variables
ERB.new(<<-'END_PRODUCT'.gsub(/^\s+/, ""), 0, "", "@product").result b
<%= PRODUCT[:name] %>
<%= PRODUCT[:desc] %>
END_PRODUCT
ERB.new(<<-'END_PRICE'.gsub(/^\s+/, ""), 0, "", "@price").result b
<%= PRODUCT[:name] %> -- <%= PRODUCT[:cost] %>
<%= PRODUCT[:desc] %>
END_PRICE
end
end
# setup template data
listings = Listings.new
listings.build
puts listings.product + "\n" + listings.price
Generates
Chicken Fried Steak
A well messages pattie, breaded and fried.
Chicken Fried Steak -- 9.95
A well messages pattie, breaded and fried.
# File 'lib/erb.rb', line 797
def initialize(str, safe_level=nil, trim_mode=nil, eoutvar='_erbout') @safe_level = safe_level compiler = make_compiler(trim_mode) set_eoutvar(compiler, eoutvar) @src, @encoding = *compiler.compile(str) @filename = nil @lineno = 0 end
Class Method Details
.version
Returns revision information for the erb.rb module.
# File 'lib/erb.rb', line 265
def self.version "erb.rb [2.1.0 #{ERB::Revision.split[1]}]" end
Instance Attribute Details
#encoding (readonly)
The encoding to eval
# File 'lib/erb.rb', line 817
attr_reader :encoding
#filename (rw)
The optional filename argument passed to Kernel.eval
when the ERB
code is run
# File 'lib/erb.rb', line 821
attr_accessor :filename
#lineno (rw)
The optional lineno argument passed to Kernel.eval
when the ERB
code is run
# File 'lib/erb.rb', line 825
attr_accessor :lineno
#src (readonly)
The Ruby code generated by ERB
# File 'lib/erb.rb', line 814
attr_reader :src
Instance Method Details
#def_class(superklass = Object, methodname = 'result')
Define unnamed class which has methodname as instance method, and return it.
example:
class MyClass_
def initialize(arg1, arg2)
@arg1 = arg1; @arg2 = arg2
end
end
filename = 'example.rhtml' # @arg1 and @arg2 are used in example.rhtml
erb = ERB.new(File.read(filename))
erb.filename = filename
MyClass = erb.def_class(MyClass_, 'render()')
print MyClass.new('foo', 123).render()
# File 'lib/erb.rb', line 921
def def_class(superklass=Object, methodname='result') cls = Class.new(superklass) def_method(cls, methodname, @filename || '(ERB)') cls end
#def_method(mod, methodname, fname = '(ERB)')
#def_module(methodname = 'erb')
Create unnamed module, define methodname as instance method of it, and return it.
example:
filename = 'example.rhtml' # 'arg1' and 'arg2' are used in example.rhtml
erb = ERB.new(File.read(filename))
erb.filename = filename
MyModule = erb.def_module('render(arg1, arg2)')
class MyClass
include MyModule
end
# File 'lib/erb.rb', line 902
def def_module(methodname='erb') mod = Module.new def_method(mod, methodname, @filename || '(ERB)') mod end
#location=(filename, lineno)
[ GitHub ]#make_compiler(trim_mode)
Creates a new compiler for ERB
. See Compiler.new for details
#new_toplevel (private)
Returns a new binding each time near TOPLEVEL_BINDING for runs that do not specify a binding.
# File 'lib/erb.rb', line 872
def new_toplevel TOPLEVEL_BINDING.dup end
#result(b = new_toplevel)
Executes the generated ERB
code to produce a completed template, returning the results of that code. (See .new for details on how this process can be affected by safe_level.)
b accepts a Binding object which is used to set the context of code evaluation.
# File 'lib/erb.rb', line 857
def result(b=new_toplevel) if @safe_level proc { $SAFE = @safe_level eval(@src, b, (@filename || '(erb)'), @lineno) }.call else eval(@src, b, (@filename || '(erb)'), @lineno) end end
#run(b = new_toplevel)
Generate results and print them. (see #result)
# File 'lib/erb.rb', line 845
def run(b=new_toplevel) print self.result(b) end
#set_eoutvar(compiler, eoutvar = '_erbout')
Can be used to set eoutvar as described in .new. It's probably easier to just use the constructor though, since calling this method requires the setup of an ERB
compiler object.
# File 'lib/erb.rb', line 837
def set_eoutvar(compiler, eoutvar = '_erbout') compiler.put_cmd = "#{eoutvar}.concat" compiler.insert_cmd = "#{eoutvar}.concat" compiler.pre_cmd = ["#{eoutvar} = ''"] compiler.post_cmd = ["#{eoutvar}.force_encoding(__ENCODING__)"] end