README.md

Tilt

Tilt is a thin interface over a bunch of different Ruby template engines in
an attempt to make their usage as generic possible. This is useful for web
frameworks, static site generators, and other systems that support multiple
template engines but don't want to code for each of them individually.

The following features are supported for all template engines (assuming the
feature is relevant to the engine):

Custom template evaluation scopes / bindings

Ability to pass locals to template evaluation

Support for passing a block to template evaluation for "yield"

Backtraces with correct filenames and line numbers

Template file caching and reloading

Fast, method-based template source compilation

The primary goal is to get all of the things listed above right for all
template engines included in the distribution.

Basic Usage

It's recommended that calling programs explicitly require template engine
libraries (like 'erb' above) at load time. Tilt attempts to lazy require the
template engine library the first time a template is created but this is
prone to error in threaded environments.

The Tilt module contains generic implementation classes for all supported
template engines. Each template class adheres to the same interface for
creation and rendering. In the instant gratification example, we let Tilt
determine the template implementation class based on the filename, but
Tilt::Template implementations can also be used directly:

If no scope is provided, the template is evaluated within the context of an
object created with Object.new.

A single Template instance's render method may be called multiple times
with different scope and locals arguments. Continuing the previous example,
we render the same compiled template but this time in jane's scope:

The template class is determined by searching for a series of decreasingly
specific name patterns. When creating a new template with
Tilt.new('views/foo.html.erb'), we check for the following template
mappings:

views/foo.html.erb

foo.html.erb

html.erb

erb

Tilt::register can also be used to select between alternative template
engines. To use Erubis instead of ERB for .erb files:

Tilt.register 'erb', Tilt::ErubisTemplate

Or, use BlueCloth for markdown instead of RDiscount:

Tilt.register 'markdown', Tilt::BlueClothTemplate

Template Compilation

Tilt can compile generated Ruby source code produced by template engines and
reuse on subsequent template invocations. Benchmarks show this yields a 5x-10x
performance increase over evaluating the Ruby source on each invocation.

Template compilation is currently supported for these template engines:
StringTemplate, ERB, Erubis, Haml, and Builder.

To enable template compilation, the Tilt::CompileSite module must be mixed in
to the scope object passed to the template's #render method. This can be
accomplished by including (with Module#include) the module in the class used
for scope objects or by extending (with Object#extend) scope objects before
passing to Template#render: