Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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