Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 413 lines (284 sloc) 12.641 kb
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
1 Tilt Templates
2 ==============
f7bcad2 Ryan Tomayko starting in on template engine docs
authored
3
2a4b2c0 Ryan Tomayko 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 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
8 * [ERB](#erb) - `Tilt::ERBTemplate`
9 * [Erubis](#erubis) - `Tilt::ErubisTemplate`
10 * [Haml](#haml) - `Tilt::HamlTemplate`
4eeaac4 Ryan Tomayko add basic liquid docs
authored
11 * [Liquid](#liquid) - `Tilt::LiquidTemplate`
5d7b643 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
12 * [Mustache](#mustache) - `Tilt::MustachTemplate`
7c28004 Ben Schwarz Did my homework for Mr Tomayko, the geography teacher.
benschwarz authored
13
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.
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
17
7c28004 Ben Schwarz Did my homework for Mr Tomayko, the geography teacher.
benschwarz authored
18 * Less - `Tilt::LessTemplate`
19 * Sass - `Tilt::SassTemplate`
5d7b643 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
20 * [Markdown](#markdown) - `Tilt::RDiscountTemplate`
23a141b Ryan Tomayko RDocTemplate specs and docs
authored
21 * [RDoc](#rdoc) - `Tilt::RDocTemplate`
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
22
23 <a name='erb'></a>
f7bcad2 Ryan Tomayko starting in on template engine docs
authored
24 ERB (`erb`, `rhtml`)
25 --------------------
26
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
27 An easy to use but powerful templating system for Ruby.
f7bcad2 Ryan Tomayko 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 Ryan Tomayko 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 Ryan Tomayko starting in on template engine docs
authored
53 ### Options
54
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
55 #### `:trim => '-'`
f7bcad2 Ryan Tomayko 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 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
65 #### `:safe => nil`
f7bcad2 Ryan Tomayko 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
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
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
e9782ef Wlodek Bzyl added Options section to Erubis
wbzyl authored
89 ### Options
90
5d7b643 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
91 #### `:trim => true`
e9782ef Wlodek Bzyl added Options section to Erubis
wbzyl authored
92
93 Delete spaces around '<% %>'. (But, spaces around '<%= %>' are preserved.)
94
95 #### `:pattern => '<% %>'`
96
97 Set pattern for embedded Ruby code.
98
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
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
4eeaac4 Ryan Tomayko add basic liquid docs
authored
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
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
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
4eeaac4 Ryan Tomayko add basic liquid docs
authored
294 ### Options
295
2a4b2c0 Ryan Tomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
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/)
4eeaac4 Ryan Tomayko add basic liquid docs
authored
329 * GitHub: [defunkt/mustache](http://github.com/defunkt/mustache)
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
330
331
332 <a name='markdown'></a>
23a141b Ryan Tomayko RDocTemplate specs and docs
authored
333 Markdown (`markdown`, `md`, `mkd`)
334 ----------------------------------
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
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,
5d7b643 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
338 HTML is used. Marking up plain text with Markdown markup is easy and
339 Markdown formatted texts are readable.
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
340
5d7b643 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
341 Markdown formatted texts are converted to HTML with the [RDiscount][]
342 engine, which is a Ruby extension over the fast [Discount][] C library.
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
343
344 ### Example
345
23a141b Ryan Tomayko RDocTemplate specs and docs
authored
346 Hello Markdown Templates
347 ========================
348
349 Hello World. This is a paragraph.
350
351 ### Usage
352
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
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
5d7b643 Ryan Tomayko tidy up TEMPLATES documentation a bit
authored
358 "<!doctype html><title></title>{%= yield %}"
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
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
23a141b Ryan Tomayko RDocTemplate specs and docs
authored
364 __NOTE:__ It's suggested that your program `require 'mustache'` at load time
365 when using this template engine in a threaded environment.
366
2f2aa38 Ryan Tomayko :smart and :filter_html options for RDiscountTemplate
authored
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.
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
380
381 ### See also
382
2f2aa38 Ryan Tomayko :smart and :filter_html options for RDiscountTemplate
authored
383 * [Markdown Syntax Documentation][markdown syntax]
384 * GitHub: [rtomayko/rdiscount][rdiscount]
6f180e3 Ryan Tomayko added markdown doc to TEMPLATES
authored
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"
23a141b Ryan Tomayko RDocTemplate specs and docs
authored
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)
Something went wrong with that request. Please try again.