Skip to content

HTTPS clone URL

Subversion checkout URL

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