docs/TEMPLATES

Tilt Templates

(See 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
  • Literate CoffeeScript - Tilt::CoffeeScriptLiterateTemplate
  • 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 (erb, rhtml)

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.

Example

Hello <%= world %>!

Usage

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!’)

Options

:trim =&gt; trim

Omits newlines and spaces around certain lines (usually those that starts with
&lt;% and ends with %&gt;). 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.

:outvar =&gt; '_erbout'

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.rb (erb, rhtml)

ERB implementation available in Ruby’s standard library.

All the documentation of ERB applies in addition to the following:

Usage

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.

Options

:trim =&gt; true

The ERB trim mode flags. This is a string consisting of any combination of the
following characters:

  • '&gt;' omits newlines for lines ending in &gt;
  • '&lt;&gt;' omits newlines for lines starting with &lt;% and ending in %&gt;
  • '%' enables processing of lines beginning with %
  • true is an alias of &lt;&gt;

:safe =&gt; nil

The $SAFE level; when set, ERB code will be run in a
separate thread with $SAFE set to the provided level.

:outvar =&gt; '_erbout'

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.

See also

Erubis (erb, rhtml, erubis)

Erubis is a fast, secure, and very extensible implementation of ERB.

All the documentation of ERB applies in addition to the following:

Usage

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.

Options

:engine_class =&gt; Erubis::Eruby

Allows you to specify a custom engine class to use instead of the
default which is Erubis::Eruby.

:escape_html =&gt; false

When true, Erubis::EscapedEruby will be used as the engine class
instead of the default. All content within &lt;%= %&gt; blocks will be
automatically html escaped.

:outvar =&gt; '_erbout'

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.

:pattern =&gt; '&lt;% %&gt;'

Set pattern for embedded Ruby code.

:trim =&gt; true

Delete spaces around &lt;% %&gt;. (But, spaces around &lt;%= %&gt; are preserved.)

See also

Haml (haml)

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)

Example

%html
%head
%title= @title
%body
%h1
Hello
= world + ‘!’

Usage

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’)
=> #
>> @title = “Hello Haml!”
>> template.render(self, :world => ‘Haml!’)
=> “

Hello Haml!

Hello Haml!

”

Or, use the Tilt::HamlTemplate class directly to process strings:

>> require ‘haml’
>> template = Tilt::HamlTemplate.new { “%h1= ‘Hello Haml!’” }
=> #
>> template.render
=> “

Hello Haml!

”

NOTE: It’s suggested that your program require 'haml' at load time when
using this template engine within a threaded environment.

Options

Please see the Haml Reference for all available options.

See also

Liquid (liquid)

Liquid is for rendering safe templates which cannot affect the
security of the server they are rendered on.

Example

{{ title }}

Hello {{ world }}!

Usage

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’)
=> #
>> scope = { :title => “Hello Liquid Templates” }
>> template.render(nil, :world => “Liquid”)
=> “

Hello Liquid Templates

Hello Liquid!

”

Or, use Tilt::LiquidTemplate directly to process strings:

>> require ‘liquid’
>> template = Tilt::LiquidTemplate.new { “

Hello Liquid!

” }
=> #
>> template.render
=> “

Hello Liquid!

”

NOTE: It’s suggested that your program require 'liquid' at load
time when using this template engine within a threaded environment.

See also

Radius (radius)

Radius is the template language used by Radiant CMS. It is
a tag language designed to be valid XML/HTML.

Example



  • Hello, World!

  • Hello, World!

  • Hello, World!


Jackpot!

See also

Textile (textile)

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.

Example

h1. Hello Textile Templates

Hello World. This is a paragraph.

Usage

NOTE: It’s suggested that your program require 'redcloth' at load time
when using this template engine in a threaded environment.

See Also

RDoc (rdoc)

RDoc is the simple text markup system that comes with Ruby’s standard
library.

Example

= Hello RDoc Templates

Hello World. This is a paragraph.

Usage

NOTE: It’s suggested that your program require 'rdoc',
require 'rdoc/markup', and require 'rdoc/markup/to_html' at load time
when using this template engine in a threaded environment.

See also

Markdown (markdown, md, mkd)

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.

Example

Hello Markdown Templates
========================

Hello World. This is a paragraph.

Usage

To wrap a Markdown formatted document with a layout:

layout = Tilt[‘erb’].new do
“<%= yield %>”
end
data = Tilt[‘md’].new { “# hello tilt” }
layout.render { data.render }
# => “

hello tilt

\n”

Options

Every implementation of Markdown should support these options, but there are
some known problems with the Kramdown and Maruku engines.

:smartypants =&gt; true|false

Set true to enable Smarty Pants style punctuation replacement.

In Kramdown this option only applies to smart quotes. It will apply a
subset of Smarty Pants (e.g. ... to …) regardless of any option.

Maruku ignores this option and always applies smart quotes (and nothing else).

:escape_html =&gt; true|false

Set true disallow raw HTML in Markdown contents. HTML is converted to
literal text by escaping &lt; characters.

Kramdown and Maruku doesn’t support this option.

See also

RDiscount (markdown, md, mkd)

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:

Usage

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.

See also