Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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