(See https://github.com/rtomayko/tilt/blob/master/TEMPLATES.md for a rendered, HTML-version of this file).
While all Tilt templates use the same basic interface for template loading and evaluation, each varies in its capabilities and available options. Detailed documentation on each supported template engine is provided below.
There are also some file extensions that have several implementations (currently ERB and Markdown). These template classes have certain features which are guaranteed to work across all the implementations. If you wish to be compatible with all of these template classes, you should only depend on the cross-implementation features.
- ERB - Generic ERB implementation (backed by erb.rb or Erubis)
- erb.rb -
Tilt::ERBTemplate - Erubis -
Tilt::ErubisTemplate - Haml -
Tilt::HamlTemplate - Liquid -
Tilt::LiquidTemplate - Nokogiri -
Tilt::NokogiriTemplate - Builder -
Tilt::BuilderTemplate - Markaby -
Tilt::MarkabyTemplate - Radius -
Tilt::RadiusTemplate
Tilt also includes support for CSS processors like LessCSS and Sass, CoffeeScript and some simple text formats.
- Less -
Tilt::LessTemplate - Sass -
Tilt::SassTemplate - Scss -
Tilt::ScssTemplate - CoffeeScript -
Tilt::CoffeeScriptTemplate - Textile -
Tilt::RedClothTemplate - Creole -
Tilt::CreoleTemplate - RDoc -
Tilt::RDocTemplate
Tilt has extensive support for Markdown, backed by one of four different implementations (depending on which are available on your system):
- Markdown - Generic Markdown implementation
- RDiscount -
Tilt::RDiscountTemplate - Redcarpet -
Tilt::RedcarpetTemplate - BlueCloth -
Tilt::BlueClothTemplate - Kramdown -
Tilt::KramdownTemplate - Maruku -
Tilt::MarukuTemplate
ERB is a simple but powerful template languge for Ruby. In Tilt it's backed by Erubis (if installed on your system) or by erb.rb (which is included in Ruby's standard library). This documentation applies to both implementations.
Hello <%= world %>!
ERB templates support custom evaluation scopes and locals:
>> require 'erb'
>> template = Tilt.new('hello.html.erb')
>> template.render(self, :world => 'World!')
=> "Hello World!"
Or, use Tilt['erb'] directly to process strings:
template = Tilt['erb'].new { "Hello <%= world %>!" }
template.render(self, :world => 'World!')
Omits newlines and spaces around certain lines (usually those that starts with
<% and ends with %>). There isn't a specification for how trimming in ERB
should work, so if you need more control over the whitespace, you should use
erb.rb or Erubis directly.
The name of the variable used to accumulate template output. This can be
any valid Ruby expression but must be assignable. By default a local
variable named _erbout is used.
ERB implementation available in Ruby's standard library.
All the documentation of ERB applies in addition to the following:
The Tilt::ERBTemplate class is registered for all files ending in .erb or
.rhtml by default, but with a lower priority than ErubisTemplate. If you
specifically want to use ERB, it's recommended to use #prefer:
Tilt.prefer Tilt::ERBTemplate
NOTE: It's suggested that your program require 'erb' at load time when
using this template engine within a threaded environment.
The ERB trim mode flags. This is a string consisting of any combination of the following characters:
'>'omits newlines for lines ending in>'<>'omits newlines for lines starting with<%and ending in%>'%'enables processing of lines beginning with%trueis an alias of<>
The $SAFE level; when set, ERB code will be run in a
separate thread with $SAFE set to the provided level.
The name of the variable used to accumulate template output. This can be
any valid Ruby expression but must be assignable. By default a local
variable named _erbout is used.
Erubis is a fast, secure, and very extensible implementation of ERB.
All the documentation of ERB applies in addition to the following:
The Tilt::ErubisTemplate class is registered for all files ending in .erb or
.rhtml by default, but with a higher priority than ERBTemplate. If you
specifically want to use Erubis, it's recommended to use #prefer:
Tilt.prefer Tilt::ErubisTemplate
NOTE: It's suggested that your program require 'erubis' at load time when
using this template engine within a threaded environment.
Allows you to specify a custom engine class to use instead of the
default which is Erubis::Eruby.
When true, Erubis::EscapedEruby will be used as the engine class
instead of the default. All content within <%= %> blocks will be
automatically html escaped.
The name of the variable used to accumulate template output. This can be
any valid Ruby expression but must be assignable. By default a local
variable named _erbout is used.
Set pattern for embedded Ruby code.
Delete spaces around <% %>. (But, spaces around <%= %> are preserved.)
Haml is a markup language that’s used to cleanly and simply describe the HTML of any web document without the use of inline code. Haml functions as a replacement for inline page templating systems such as PHP, ASP, and ERB, the templating language used in most Ruby on Rails applications. However, Haml avoids the need for explicitly coding HTML into the template, because it itself is a description of the HTML, with some code to generate dynamic content. (more)
%html
%head
%title= @title
%body
%h1
Hello
= world + '!'
The Tilt::HamlTemplate class is registered for all files ending in .haml
by default. Haml templates support custom evaluation scopes and locals:
>> require 'haml'
>> template = Tilt.new('hello.haml')
=> #<Tilt::HamlTemplate @file='hello.haml'>
>> @title = "Hello Haml!"
>> template.render(self, :world => 'Haml!')
=> "
<html>
<head>
<title>Hello Haml!</title>
</head>
<body>
<h1>Hello Haml!</h1>
</body>
</html>"
Or, use the Tilt::HamlTemplate class directly to process strings:
>> require 'haml'
>> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
=> #<Tilt::HamlTemplate @file=nil ...>
>> template.render
=> "<h1>Hello Haml!</h1>"
NOTE: It's suggested that your program require 'haml' at load time when
using this template engine within a threaded environment.
Please see the Haml Reference for all available options.
Liquid is for rendering safe templates which cannot affect the security of the server they are rendered on.
<html>
<head>
<title>{{ title }}</title>
</head>
<body>
<h1>Hello {{ world }}!</h1>
</body>
</html>
Tilt::LiquidTemplate is registered for all files ending in .liquid by
default. Liquid templates support locals and objects that respond to
#to_h as scopes:
>> require 'liquid'
>> require 'tilt'
>> template = Tilt.new('hello.liquid')
=> #<Tilt::LiquidTemplate @file='hello.liquid'>
>> scope = { :title => "Hello Liquid Templates" }
>> template.render(nil, :world => "Liquid")
=> "
<html>
<head>
<title>Hello Liquid Templates</title>
</head>
<body>
<h1>Hello Liquid!</h1>
</body>
</html>"
Or, use Tilt::LiquidTemplate directly to process strings:
>> require 'haml'
>> template = Tilt::LiquidTemplate.new { "<h1>Hello Liquid!</h1>" }
=> #<Tilt::LiquidTemplate @file=nil ...>
>> template.render
=> "<h1>Hello Liquid!</h1>"
NOTE: It's suggested that your program require 'liquid' at load
time when using this template engine within a threaded environment.
Radius is the template language used by Radiant CMS. It is a tag language designed to be valid XML/HTML.
<html>
<body>
<h1><r:title /></h1>
<ul class="<r:type />">
<r:repeat times="3">
<li><r:hello />!</li>
</r:repeat>
</ul>
<r:yield />
</body>
</html>
To render a template such as the one above.
scope = OpenStruct.new
scope.title = "Radius Example"
scope.hello = "Hello, World!"
require 'radius'
template = Tilt::RadiusTemplate.new('example.radius', :tag_prefix=>'r')
template.render(scope, :type=>'hlist'){ "Jackpot!" }
The result will be:
<html>
<body>
<h1>Radius Example</h1>
<ul class="hlist">
<li>Hello, World!</li>
<li>Hello, World!</li>
<li>Hello, World!</li>
</ul>
Jackpot!
</body>
</html>
Textile is a lightweight markup language originally developed by Dean Allen and billed as a "humane Web text generator". Textile converts its marked-up text input to valid, well-formed XHTML and also inserts character entity references for apostrophes, opening and closing single and double quotation marks, ellipses and em dashes.
Textile formatted texts are converted to HTML with the RedCloth engine, which is a Ruby extension written in C.
h1. Hello Textile Templates
Hello World. This is a paragraph.
NOTE: It's suggested that your program require 'redcloth' at load time
when using this template engine in a threaded environment.
RDoc is the simple text markup system that comes with Ruby's standard library.
= Hello RDoc Templates
Hello World. This is a paragraph.
NOTE: It's suggested that your program require 'rdoc/markup' and
require 'rdoc/markup/to_html' at load time when using this template
engine in a threaded environment.
[Markdown][markdown] is a lightweight markup language, created by John Gruber and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML is used. Marking up plain text with Markdown markup is easy and Markdown formatted texts are readable.
Markdown formatted texts are converted to HTML with one of these libraries:
- RDiscount -
Tilt::RDiscountTemplate - Redcarpet -
Tilt::RedcarpetTemplate - BlueCloth -
Tilt::BlueClothTemplate - Kramdown -
Tilt::KramdownTemplate - Maruku -
Tilt::MarukuTemplate
Tilt will use fallback mode (as documented in the README) for determining which library to use. RDiscount has highest priority - Maruku has lowest.
Hello Markdown Templates
========================
Hello World. This is a paragraph.
To wrap a Markdown formatted document with a layout:
layout = Tilt['erb'].new do
"<!doctype html><title></title><%= yield %>"
end
data = Tilt['md'].new { "# hello tilt" }
layout.render { data.render }
# => "<!doctype html><title></title><h1>hello tilt</h1>\n"
Every implementation of Markdown should support these options, but there are some known problems with the Kramdown and Maruku engines.
Set true to enable Smarty Pants
style punctuation replacement.
Set true disallow raw HTML in Markdown contents. HTML is converted to
literal text by escaping < characters.
Discount is an implementation of the Markdown markup language in C. RDiscount is a Ruby wrapper around Discount.
All the documentation of Markdown applies in addition to the following:
The Tilt::RDiscountTemplate class is registered for all files ending in
.markdown, .md or .mkd by default with the highest priority. If you
specifically want to use RDiscount, it's recommended to use #prefer:
Tilt.prefer Tilt::RDiscountTemplate
NOTE: It's suggested that your program require 'erubis' at load time when
using this template engine within a threaded environment.
- Discount
- RDiscount
- GitHub: rtomayko/rdiscount