Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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