Skip to content

HTTPS clone URL

Subversion checkout URL

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