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