Permalink
Newer
Older
100644 413 lines (284 sloc) 12.3 KB
1
Tilt Templates
2
==============
4
While all Tilt templates use the same basic interface for template loading and
5
evaluation, each varies in its capabilities and available options. Detailed
6
documentation on each supported template engine is provided below.
7
8
* [ERB](#erb) - `Tilt::ERBTemplate`
9
* [Erubis](#erubis) - `Tilt::ErubisTemplate`
10
* [Haml](#haml) - `Tilt::HamlTemplate`
11
* [Liquid](#liquid) - `Tilt::LiquidTemplate`
12
* [Mustache](#mustache) - `Tilt::MustachTemplate`
14
Tilt includes support for CSS processors like [lesscss](http://lesscss.org)
15
and [sass](http://sass-lang.com/), in addition, it also supports simple
16
text formats.
18
* Less - `Tilt::LessTemplate`
19
* Sass - `Tilt::SassTemplate`
20
* [Markdown](#markdown) - `Tilt::RDiscountTemplate`
21
* [RDoc](#rdoc) - `Tilt::RDocTemplate`
22
23
<a name='erb'></a>
24
ERB (`erb`, `rhtml`)
25
--------------------
26
27
An easy to use but powerful templating system for Ruby.
28
29
### Example
30
31
Hello <%= world %>!
32
33
### Usage
34
35
The `Tilt::ERBTemplate` class is registered for all files ending in `.erb` or
36
`.rhtml` by default. ERB templates support custom evaluation scopes and locals:
37
38
>> require 'erb'
39
>> template = Tilt.new('hello.html.erb', :trim => '<>')
40
=> #<Tilt::ERBTemplate @file='hello.html.erb'>
41
>> template.render(self, :world => 'World!')
42
=> "Hello World!"
43
44
Or, use the `Tilt::ERBTemplate` class directly to process strings:
45
46
require 'erb'
47
template = Tilt::ERBTemplate.new(nil, :trim => '<>') { "Hello <%= world %>!" }
48
template.render(self, :world => 'World!')
49
50
__NOTE:__ It's suggested that your program `require 'erb'` at load time when
51
using this template engine within a threaded environment.
52
53
### Options
54
55
#### `:trim => '-'`
56
57
The ERB trim mode flags. This is a string consisting
58
of any combination of the following characters:
59
60
* `'>'` omits newlines for lines ending in `>`
61
* `'<>'` omits newlines for lines starting with `<%` and ending in `%>`
62
* `'-'` omits newlines for lines ending in `-%>`.
63
* `'%'` enables processing of lines beginning with `%`
64
65
#### `:safe => nil`
66
67
The `$SAFE` level; when set, ERB code will be run in a
68
separate thread with `$SAFE` set to the provided level.
69
70
### See also
71
72
* [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
73
74
75
<a name='erubis'></a>
76
Erubis (`erubis`)
77
-----------------
78
79
Erubis is a fast, secure, and very extensible implementation of eRuby.
80
81
### Usage
82
83
To use Erubis instead of ERB for all `.erb` and `.rhtml` files, register
84
the extensions as follows:
85
86
Tilt.register 'erb', Tilt::ErubisTemplate
87
Tilt.register 'rhtml', Tilt::ErubisTemplate
88
89
### Options
90
91
#### `:trim => true`
92
93
Delete spaces around '<% %>'. (But, spaces around '<%= %>' are preserved.)
94
95
#### `:pattern => '<% %>'`
96
97
Set pattern for embedded Ruby code.
98
99
See the [ERB](#erb) template documentation for examples, usage, and options.
100
101
__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
102
using this template engine within a threaded environment.
103
104
### See also
105
106
* [Erubis Home](http://www.kuwata-lab.com/erubis/)
107
* [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
108
109
110
<a name='haml'></a>
111
Haml (`haml`)
112
-------------
113
114
Haml is a markup language that’s used to cleanly and simply describe the HTML of
115
any web document without the use of inline code. Haml functions as a replacement
116
for inline page templating systems such as PHP, ASP, and ERB, the templating
117
language used in most Ruby on Rails applications. However, Haml avoids the
118
need for explicitly coding HTML into the template, because it itself is a
119
description of the HTML, with some code to generate dynamic content.
120
([more](http://haml-lang.com/about.html))
121
122
123
### Example
124
125
%html
126
%head
127
%title= @title
128
%body
129
%h1
130
Hello
131
= world + '!'
132
133
### Usage
134
135
The `Tilt::HamlTemplate` class is registered for all files ending in `.haml`
136
by default. Haml templates support custom evaluation scopes and locals:
137
138
>> require 'haml'
139
>> template = Tilt.new('hello.haml')
140
=> #<Tilt::HamlTemplate @file='hello.haml'>
141
>> @title = "Hello Haml!"
142
>> template.render(self, :world => 'Haml!')
143
=> "
144
<html>
145
<head>
146
<title>Hello Haml!</title>
147
</head>
148
<body>
149
<h1>Hello Haml!</h1>
150
</body>
151
</html>"
152
153
Or, use the `Tilt::HamlTemplate` class directly to process strings:
154
155
>> require 'haml'
156
>> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
157
=> #<Tilt::HamlTemplate @file=nil ...>
158
>> template.render
159
=> "<h1>Hello Haml!</h1>"
160
161
__NOTE:__ It's suggested that your program `require 'haml'` at load time when
162
using this template engine within a threaded environment.
163
164
### Options
165
166
#### `:format => :xhtml`
167
168
Determines the output format. The default is `:xhtml`. Other options are
169
`:html4` and `:html5`, which are identical to `:xhtml` except there are no
170
self-closing tags, the XML prolog is ignored and correct DOCTYPEs are generated.
171
172
#### `:escape_html => false`
173
174
Sets whether or not to escape HTML-sensitive characters in script. If this is
175
true, `=` behaves like `&=;` otherwise, it behaves like `!=`. Note that if this
176
is set, `!=` should be used for yielding to subtemplates and rendering partials.
177
Defaults to false.
178
179
#### `:ugly => false`
180
181
If set to true, Haml makes no attempt to properly indent or format the HTML
182
output. This causes the rendering to be done much quicker than it would
183
otherwise, but makes viewing the source unpleasant. Defaults to false.
184
185
#### `:suppress_eval => false`
186
187
Whether or not attribute hashes and Ruby scripts designated by `=` or `~` should
188
be evaluated. If this is true, said scripts are rendered as empty strings.
189
Defaults to false.
190
191
#### `:attr_wrapper => "'"`
192
193
The character that should wrap element attributes. This defaults to `'` (an
194
apostrophe). Characters of this type within the attributes will be escaped (e.g.
195
by replacing them with `&apos;`) if the character is an apostrophe or a
196
quotation mark.
197
198
#### `:autoclose => %w[meta img link br hr input area param col base]`
199
200
A list of tag names that should be automatically self-closed if they have no
201
content. Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area',
202
'param', 'col', 'base']`.
203
204
#### `:preserve => %w[textarea pre]`
205
206
A list of tag names that should automatically have their newlines preserved
207
using the `Haml::Helpers#preserve` helper. This means that any content given on
208
the same line as the tag will be preserved. For example, `%textarea= "Foo\nBar"`
209
compiles to `<textarea>Foo&#x000A;Bar</textarea>`. Defaults to `['textarea',
210
'pre']`.
211
212
#### `:encoding => 'utf-8'`
213
214
The encoding to use for the HTML output. Only available in Ruby 1.9 or higher.
215
This can be a string or an Encoding Object. Note that Haml does not
216
automatically re-encode Ruby values; any strings coming from outside the
217
application should be converted before being passed into the Haml template.
218
Defaults to `Encoding.default_internal` or, if that's not set, `"utf-8"`.
219
220
### See also
221
222
* [#haml.docs](http://haml-lang.com/docs.html)
223
* [Haml Tutorial](http://haml-lang.com/tutorial.html)
224
* [Haml Reference](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html)
225
* [Whitespace Preservation](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html#whitespace_preservation)
226
227
228
<a name='liquid'></a>
229
Liquid (`liquid`)
230
-----------------
231
232
Liquid is for rendering safe templates which cannot affect the security
233
of the server they are rendered on.
234
235
### Example
236
237
<html>
238
<head>
239
<title>{{ title }}</title>
240
</head>
241
<body>
242
<h1>Hello {{ world }}!</h1>
243
</body>
244
</html>
245
246
### Usage
247
248
`Tilt::LiquidTemplate` is registered for all files ending in `.liquid` by
249
default. Liquid templates support locals and objects that respond to
250
`#to_h` as scopes:
251
252
>> require 'liquid'
253
>> require 'tilt'
254
>> template = Tilt.new('hello.liquid')
255
=> #<Tilt::LiquidTemplate @file='hello.liquid'>
256
>> scope = { :title => "Hello Liquid Templates" }
257
>> template.render(nil, :world => "Liquid")
258
=> "
259
<html>
260
<head>
261
<title>Hello Liquid Templates</title>
262
</head>
263
<body>
264
<h1>Hello Liquid!</h1>
265
</body>
266
</html>"
267
268
Or, use `Tilt::LiquidTemplate` directly to process strings:
269
270
>> require 'haml'
271
>> template = Tilt::HamlTemplate.new { "<h1>Hello Liquid!</h1>" }
272
=> #<Tilt::LiquidTemplate @file=nil ...>
273
>> template.render
274
=> "<h1>Hello Liquid!</h1>"
275
276
__NOTE:__ It's suggested that your program `require 'liquid'` at load
277
time when using this template engine within a threaded environment.
278
279
### See also
280
281
* [Liquid for Programmers](http://wiki.github.com/tobi/liquid/liquid-for-programmers)
282
* [Liquid Docs](http://liquid.rubyforge.org/)
283
* GitHub: [tobi/liquid](http://github.com/tobi/liquid/)
284
285
<a name='mustache'></a>
286
Mustache (`mustache`)
287
---------------------
288
289
Mustache is a framework-agnostic way to render logic-free views.
290
291
__NOTE:__ It's suggested that your program `require 'mustache'` at load time
292
when using this template engine in a threaded environment.
293
294
### Options
295
296
#### `:path => Dir.pwd`
297
298
The base path where mustache templates (`.html` files) are located. Defaults to
299
the current working directory.
300
301
#### `:template_extension => 'html'`
302
303
The file extension used on mustache templates. Default is `'html'`.
304
305
#### `:namespace => Object`
306
307
The class or module where View classes are located. If you have
308
`Hurl::App::Views`, namespace should be `Hurl:App`. This defaults to `Object`,
309
causing `::Views` to be searched for classes.
310
311
#### `:mustaches => nil`
312
313
Where mustache views (.rb files) are located, or nil to disable auto-requiring
314
of views based on template names. By default, the view file is assumed to be in
315
the same directory as the template file.
316
317
All other options are assumed to be attribute writer's on the Mustache
318
class and are set when a template is compiled. They are:
319
320
#### `:view => nil`
321
322
The Mustache subclass that should be used a the view. When this option is
323
specified, the template file will be determined from the view class, and the
324
`:namespace` and `:mustaches` options are irrelevant.
325
326
### See also
327
328
* [Mustache Docs](http://defunkt.github.com/mustache/)
329
* GitHub: [defunkt/mustache](http://github.com/defunkt/mustache)
330
331
332
<a name='markdown'></a>
333
Markdown (`markdown`, `md`, `mkd`)
334
----------------------------------
335
336
Markdown is a lightweight markup language, created by John Gruber and
337
Aaron Swartz. For any markup that is not covered by Markdown’s syntax,
338
HTML is used. Marking up plain text with Markdown markup is easy and
339
Markdown formatted texts are readable.
341
Markdown formatted texts are converted to HTML with the [RDiscount][]
342
engine, which is a Ruby extension over the fast [Discount][] C library.
343
344
### Example
345
346
Hello Markdown Templates
347
========================
348
349
Hello World. This is a paragraph.
350
351
### Usage
352
353
To wrap a Markdown formatted document with a layout:
354
355
require 'erubis'
356
require 'rdiscount'
357
layout = Tilt::ErubisTemplate.new(nil, :pattern => '\{% %\}') do
358
"<!doctype html><title></title>{%= yield %}"
359
end
360
data = Tilt::RDiscountTemplate.new { "# hello tilt" }
361
layout.render { data.render }
362
# => "<!doctype html><title></title><h1>hello tilt</h1>\n"
363
364
__NOTE:__ It's suggested that your program `require 'mustache'` at load time
365
when using this template engine in a threaded environment.
366
367
### Options
368
369
RDiscount supports a variety of flags that control its behavior:
370
371
#### `:smart => true|false`
372
373
Set `true` to enable [Smarty Pants](http://daringfireball.net/projects/smartypants/)
374
style punctuation replacement.
375
376
#### `:filter_html => true|false`
377
378
Set `true` disallow raw HTML in Markdown contents. HTML is converted to
379
literal text by escaping `<` characters.
380
381
### See also
382
383
* [Markdown Syntax Documentation][markdown syntax]
384
* GitHub: [rtomayko/rdiscount][rdiscount]
385
386
[discount]: http://www.pell.portland.or.us/~orc/Code/discount/ "Discount"
387
[rdiscount]: http://github.com/rtomayko/rdiscount/ "RDiscount"
388
[markdown syntax]: (http://daringfireball.net/projects/markdown/syntax/) "Markdown Syntax"
389
390
391
<a name='rdoc'></a>
392
RDoc (`rdoc`)
393
-------------
394
395
RDoc is the simple text markup system that comes with Ruby's standard
396
library.
397
398
### Usage
399
400
__NOTE:__ It's suggested that your program `require 'rdoc/markup'` and
401
`require 'rdoc/markup/to_html'` at load time when using this template
402
engine in a threaded environment.
403
404
### Example
405
406
= Hello RDoc Templates
407
408
Hello World. This is a paragraph.
409
410
### See also
411
412
* [RDoc](http://rdoc.sourceforge.net/doc/index.html)