Tilt Templates

(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 (`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 => trim`

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.

`:outvar => '_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 => true`

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 %
true is an alias of <>

`:safe => nil`

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

`:outvar => '_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.

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 => Erubis::Eruby`

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

`:escape_html => false`

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

`:outvar => '_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 => '<% %>'`

Set pattern for embedded Ruby code.

`:trim => true`

Delete spaces around <% %>. (But, spaces around <%= %> are preserved.)

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')
=> #<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.

Options

Please see the Haml Reference for all available options.

Liquid (`liquid`)

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

Example

<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <h1>Hello {{ world }}!</h1>
  </body>
</html>

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')
=> #<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 (`radius`)

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

Example

<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>

Usage

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 (`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.

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/markup' and require 'rdoc/markup/to_html' at load time when using this template engine in a threaded environment.

Markdown (`markdown`, `md`, `mkd`)

[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.

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
  "<!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"

Options

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

`:smartypants => true|false`

Set true to enable Smarty Pants style punctuation replacement.

`:escape_html => true|false`

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

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.

TEMPLATES.md 15 KB History Raw

Tilt Templates

ERB (erb, rhtml)

Example

Usage

Options

:trim => trim

:outvar => '_erbout'

erb.rb (erb, rhtml)

Usage

Options

:trim => true

:safe => nil

:outvar => '_erbout'

See also

Erubis (erb, rhtml, erubis)

Usage

Options

:engine_class => Erubis::Eruby

:escape_html => false

:outvar => '_erbout'

:pattern => '<% %>'

:trim => true

See also

Haml (haml)

Example

Usage

Options

See also

Liquid (liquid)

Example

Usage

See also

Radius (radius)

Example

Usage

See also

Textile (textile)

Example

Usage

See Also

RDoc (rdoc)

Example

Usage

See also

Markdown (markdown, md, mkd)

Example

Usage

Options

:smartypants => true|false

:escape_html => true|false

See also

RDiscount (markdown, md, mkd)

Usage

See also

TEMPLATES.md 15 KB

History Raw

ERB (`erb`, `rhtml`)

`:trim => trim`

`:outvar => '_erbout'`

erb.rb (`erb`, `rhtml`)

`:trim => true`

`:safe => nil`

`:outvar => '_erbout'`

Erubis (`erb`, `rhtml`, `erubis`)

`:engine_class => Erubis::Eruby`

`:escape_html => false`

`:outvar => '_erbout'`

`:pattern => '<% %>'`

`:trim => true`

Haml (`haml`)

Liquid (`liquid`)

Radius (`radius`)

Textile (`textile`)

RDoc (`rdoc`)

Markdown (`markdown`, `md`, `mkd`)

`:smartypants => true|false`

`:escape_html => true|false`

RDiscount (`markdown`, `md`, `mkd`)