Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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