Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 375 lines (244 sloc) 8.735 kB
f0857e5 @defunkt rtemplate => mustache
defunkt authored
1 Mustache
6ee6bcf @defunkt first draft
defunkt authored
2 =========
3
02edd2c @defunkt references make the first paragraph it read easier
defunkt authored
4 Inspired by [ctemplate][1] and [et][2], Mustache is a
5 framework-agnostic way to render logic-free views.
6ee6bcf @defunkt first draft
defunkt authored
6
b32c566 @defunkt quote ctemplates
defunkt authored
7 As ctemplates says, "It emphasizes separating logic from presentation:
8 it is impossible to embed application logic in this template language."
3aad2f3 @defunkt docs
defunkt authored
9
dd5ced9 @defunkt more links in the readme
defunkt authored
10 For a list of implementations (other than Ruby) and tips, see
11 <http://defunkt.github.com/mustache/>.
12
0b217cf @defunkt talk about tags first. they're important.
defunkt authored
13
3aad2f3 @defunkt docs
defunkt authored
14 Overview
15 --------
16
f0857e5 @defunkt rtemplate => mustache
defunkt authored
17 Think of Mustache as a replacement for your views. Instead of views
3aad2f3 @defunkt docs
defunkt authored
18 consisting of ERB or HAML with random helpers and arbitrary logic,
19 your views are broken into two parts: a Ruby class and an HTML
20 template.
21
22 We call the Ruby class the "view" and the HTML template the
23 "template."
24
25 All your logic, decisions, and code is contained in your view. All
26 your markup is contained in your template. The template does nothing
d5258f3 @defunkt whitespace
defunkt authored
27 but reference methods in your view.
3aad2f3 @defunkt docs
defunkt authored
28
29 This strict separation makes it easier to write clean templates,
30 easier to test your views, and more fun to work on your app's front end.
31
0b217cf @defunkt talk about tags first. they're important.
defunkt authored
32
1d6dfee @defunkt why?
defunkt authored
33 Why?
34 ----
35
36 I like writing Ruby. I like writing HTML. I like writing JavaScript.
37
38 I don't like writing ERB, Haml, Liquid, Django Templates, putting Ruby
39 in my HTML, or putting JavaScript in my HTML.
40
41
3aad2f3 @defunkt docs
defunkt authored
42 Usage
43 -----
44
debca50 Quick example.
Francesc Esplugas authored
45 Quick example:
46
47 >> require 'mustache'
48 => true
49 >> Mustache.render("Hello {{planet}}", :planet => "World!")
50 => "Hello World!"
51
3aad2f3 @defunkt docs
defunkt authored
52 We've got an `examples` folder but here's the canonical one:
53
f0857e5 @defunkt rtemplate => mustache
defunkt authored
54 class Simple < Mustache
3aad2f3 @defunkt docs
defunkt authored
55 def name
56 "Chris"
57 end
58
59 def value
60 10_000
61 end
62
63 def taxed_value
64 value - (value * 0.4)
65 end
66
67 def in_ca
68 true
69 end
70 end
71
72 We simply create a normal Ruby class and define methods. Some methods
73 reference others, some return values, some return only booleans.
74
75 Now let's write the template:
76
77 Hello {{name}}
78 You have just won ${{value}}!
79 {{#in_ca}}
80 Well, ${{taxed_value}}, after taxes.
81 {{/in_ca}}
82
83 This template references our view methods. To bring it all together,
84 here's the code to render actual HTML;
85
9b245dd @defunkt `render` is the new `to_html`
defunkt authored
86 Simple.render
3aad2f3 @defunkt docs
defunkt authored
87
88 Which returns the following:
89
90 Hello Chris
91 You have just won $10000!
92 Well, $6000.0, after taxes.
93
94 Simple.
95
0b217cf @defunkt talk about tags first. they're important.
defunkt authored
96
97 Tag Types
98 ---------
99
dd5ced9 @defunkt more links in the readme
defunkt authored
100 For a language-agnostic overview of Mustache's template syntax, see
101 the `mustache(5)` manpage or
102 <http://defunkt.github.com/mustache/mustache.5.html>.
3e42d49 @defunkt document Set Delimiter
defunkt authored
103
104
6eb4df0 @defunkt steal Escaping section from mustache.js
defunkt authored
105 Escaping
106 --------
107
108 Mustache does escape all values when using the standard double
109 Mustache syntax. Characters which will be escaped: `& \ " < >`. To
110 disable escaping, simply use tripple mustaches like
111 `{{{unescaped_variable}}}`.
112
113 Example: Using `{{variable}}` inside a template for `5 > 2` will
114 result in `5 &gt; 2`, where as the usage of `{{{variable}}}` will
115 result in `5 > 2`.
116
117
04e852b @defunkt explain the dict style
defunkt authored
118 Dict-Style Views
119 ----------------
120
121 ctemplate and friends want you to hand a dictionary to the template
515de91 @defunkt Dict example uses Winner to be more explicit, less confusing
defunkt authored
122 processor. Mustache supports a similar concept. Feel free to mix the
123 class-based and this more procedural style at your leisure.
04e852b @defunkt explain the dict style
defunkt authored
124
07144e4 @defunkt Update readme with .html => .mustache change
defunkt authored
125 Given this template (winner.mustache):
04e852b @defunkt explain the dict style
defunkt authored
126
127 Hello {{name}}
128 You have just won ${{value}}!
129
130 We can fill in the values at will:
d5258f3 @defunkt whitespace
defunkt authored
131
515de91 @defunkt Dict example uses Winner to be more explicit, less confusing
defunkt authored
132 view = Winner.new
133 view[:name] = 'George'
134 view[:value] = 100
135 view.render
04e852b @defunkt explain the dict style
defunkt authored
136
137 Which returns:
d5258f3 @defunkt whitespace
defunkt authored
138
04e852b @defunkt explain the dict style
defunkt authored
139 Hello George
140 You have just won $100!
141
142 We can re-use the same object, too:
143
515de91 @defunkt Dict example uses Winner to be more explicit, less confusing
defunkt authored
144 view[:name] = 'Tony'
145 view.render
04e852b @defunkt explain the dict style
defunkt authored
146 Hello Tony
147 You have just won $100!
148
0b217cf @defunkt talk about tags first. they're important.
defunkt authored
149
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
150 Templates
151 ---------
152
153 A word on templates. By default, a view will try to find its template
154 on disk by searching for an HTML file in the current directory that
155 follows the classic Ruby naming convention.
156
07144e4 @defunkt Update readme with .html => .mustache change
defunkt authored
157 TemplatePartial => ./template_partial.mustache
d5258f3 @defunkt whitespace
defunkt authored
158
3291a2d @defunkt document template_extension in the README
defunkt authored
159 You can set the search path using `Mustache.template_path`. It can be set on a
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
160 class by class basis:
161
f0857e5 @defunkt rtemplate => mustache
defunkt authored
162 class Simple < Mustache
3291a2d @defunkt document template_extension in the README
defunkt authored
163 self.template_path = File.dirname(__FILE__)
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
164 ... etc ...
165 end
166
07144e4 @defunkt Update readme with .html => .mustache change
defunkt authored
167 Now `Simple` will look for `simple.mustache` in the directory it resides
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
168 in, no matter the cwd.
169
170 If you want to just change what template is used you can set
5b3b4c3 @judofyr Compile into a Proc (for speed). This required more changes:
judofyr authored
171 `Mustache.template_file` directly:
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
172
07144e4 @defunkt Update readme with .html => .mustache change
defunkt authored
173 Simple.template_file = './blah.mustache'
d5258f3 @defunkt whitespace
defunkt authored
174
3291a2d @defunkt document template_extension in the README
defunkt authored
175 Mustache also allows you to define the extension it'll use.
176
177 Simple.template_extension = 'xml'
178
179 Given all other defaults, the above line will cause Mustache to look
180 for './blah.xml'
181
182 Feel free to set the template directly:
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
183
5b3b4c3 @judofyr Compile into a Proc (for speed). This required more changes:
judofyr authored
184 Simple.template = 'Hi {{person}}!'
185
3291a2d @defunkt document template_extension in the README
defunkt authored
186 Or set a different template for a single instance:
5b3b4c3 @judofyr Compile into a Proc (for speed). This required more changes:
judofyr authored
187
671f6aa @defunkt document template options and make template_file configurable
defunkt authored
188 Simple.new.template = 'Hi {{person}}!'
189
190 Whatever works.
191
0b217cf @defunkt talk about tags first. they're important.
defunkt authored
192
40313b9 @defunkt Added autoloading
defunkt authored
193 Views
194 -----
195
196 Mustache supports a bit of magic when it comes to views. If you're
197 authoring a plugin or extension for a web framework (Sinatra, Rails,
198 etc), check out the `view_namespace` and `view_path` settings on the
199 `Mustache` class. They will surely provide needed assistance.
200
201
70af848 @defunkt helpers?!
defunkt authored
202 Helpers
203 -------
204
205 What about global helpers? Maybe you have a nifty `gravatar` function
d5258f3 @defunkt whitespace
defunkt authored
206 you want to use in all your views? No problem.
70af848 @defunkt helpers?!
defunkt authored
207
208 This is just Ruby, after all.
209
210 module ViewHelpers
211 def gravatar(email, size = 30)
212 gravatar_id = Digest::MD5.hexdigest(email.to_s.strip.downcase)
213 gravatar_for_id(gravatar_id, size)
214 end
215
216 def gravatar_for_id(gid, size = 30)
217 "#{gravatar_host}/avatar/#{gid}?s=#{size}"
218 end
219
220 def gravatar_host
221 @ssl ? 'https://secure.gravatar.com' : 'http://www.gravatar.com'
222 end
223 end
224
d5258f3 @defunkt whitespace
defunkt authored
225 Then just include it:
70af848 @defunkt helpers?!
defunkt authored
226
f0857e5 @defunkt rtemplate => mustache
defunkt authored
227 class Simple < Mustache
70af848 @defunkt helpers?!
defunkt authored
228 include ViewHelpers
229
230 def name
231 "Chris"
232 end
233
234 def value
235 10_000
236 end
237
238 def taxed_value
239 value - (value * 0.4)
240 end
241
242 def in_ca
243 true
244 end
245 end
246
247 Great, but what about that `@ssl` ivar in `gravatar_host`? There are
248 many ways we can go about setting it.
249
f0857e5 @defunkt rtemplate => mustache
defunkt authored
250 Here's on example which illustrates a key feature of Mustache: you
70af848 @defunkt helpers?!
defunkt authored
251 are free to use the `initialize` method just as you would in any
252 normal class.
253
f0857e5 @defunkt rtemplate => mustache
defunkt authored
254 class Simple < Mustache
70af848 @defunkt helpers?!
defunkt authored
255 include ViewHelpers
256
257 def initialize(ssl = false)
258 @ssl = ssl
259 end
260
261 ... etc ...
262 end
263
264 Now:
265
9b245dd @defunkt `render` is the new `to_html`
defunkt authored
266 Simple.new(request.ssl?).render
70af848 @defunkt helpers?!
defunkt authored
267
268 Convoluted but you get the idea.
269
270
d7d6f66 @defunkt mention sinatra integration in README
defunkt authored
271 Sinatra
272 -------
273
274 Mustache ships with Sinatra integration. Please see
275 `lib/mustache/sinatra.rb` or
fe2effe @defunkt README improvements
defunkt authored
276 <http://github.com/defunkt/mustache/blob/master/lib/mustache/sinatra.rb>
277 for complete documentation.
d7d6f66 @defunkt mention sinatra integration in README
defunkt authored
278
ca40124 @defunkt reference the mustache-sinatra-example
defunkt authored
279 An example Sinatra application is also provided:
280 <http://github.com/defunkt/mustache-sinatra-example>
281
d7d6f66 @defunkt mention sinatra integration in README
defunkt authored
282
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
283 [Rack::Bug][4]
4891479 @defunkt Added `mustache` script for rendering templates on the command line.
defunkt authored
284 --------------
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
285
286 Mustache also ships with a `Rack::Bug` panel. In your `config.ru` add
287 the following code:
288
289 require 'rack/bug/panels/mustache_panel'
290 use Rack::Bug::MustachePanel
291
292 Using Rails? Add this to your initializer or environment file:
293
294 require 'rack/bug/panels/mustache_panel'
295 config.middleware.use "Rack::Bug::MustachePanel"
296
e5ae462 @defunkt screenshot!
defunkt authored
297 [![Rack::Bug](http://img.skitch.com/20091027-xyf4h1yxnefpp7usyddrcmc7dn.png)][5]
298
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
299
da44c7e @defunkt Add mustache.vim [Juvenn Woo]
defunkt authored
300 Vim
301 ---
302
303 Thanks to [Juvenn Woo](http://github.com/juvenn) for mustache.vim. It
304 is included under the contrib/ directory.
305
dd5ced9 @defunkt more links in the readme
defunkt authored
306 See <http://gist.github.com/323622> for installation instructions.
da44c7e @defunkt Add mustache.vim [Juvenn Woo]
defunkt authored
307
fe2effe @defunkt README improvements
defunkt authored
308
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
309 Emacs
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
310 -----
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
311
b8ecafc @defunkt mustache.mode.el
defunkt authored
312 mustache-mode.el is included under the contrib/ directory for any
313 Emacs users. Based on Google's tpl-mode for ctemplates, it adds
314 support for Mustache's more lenient tag values and includes a few
315 commands for your editing pleasure.
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
316
dd5ced9 @defunkt more links in the readme
defunkt authored
317 See <http://gist.github.com/323619> for installation instructions.
318
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
319
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
320 TextMate
321 --------
322
dd5ced9 @defunkt more links in the readme
defunkt authored
323 [Mustache.tmbundle](http://github.com/defunkt/Mustache.tmbundle)
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
324
dd5ced9 @defunkt more links in the readme
defunkt authored
325 See <http://gist.github.com/323624> for installation instructions.
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
326
fe2effe @defunkt README improvements
defunkt authored
327
4891479 @defunkt Added `mustache` script for rendering templates on the command line.
defunkt authored
328 Command Line
329 ------------
330
dd5ced9 @defunkt more links in the readme
defunkt authored
331 See `mustache(1)` man page or
332 <http://defunkt.github.com/mustache/mustache.1.html>
333 for command line docs.
4891479 @defunkt Added `mustache` script for rendering templates on the command line.
defunkt authored
334
fe2effe @defunkt README improvements
defunkt authored
335
b6e396f @defunkt add installation and docs
defunkt authored
336 Installation
337 ------------
338
dd5ced9 @defunkt more links in the readme
defunkt authored
339 ### [RubyGems](http://rubygems.org/)
b6e396f @defunkt add installation and docs
defunkt authored
340
341 $ gem install mustache
d5258f3 @defunkt whitespace
defunkt authored
342
b6e396f @defunkt add installation and docs
defunkt authored
343 ### [Rip](http://hellorip.com)
344
345 $ rip install git://github.com/defunkt/mustache.git
346
fe2effe @defunkt README improvements
defunkt authored
347
05bedeb @defunkt acknowledgements
defunkt authored
348 Acknowledgements
349 ----------------
350
351 Thanks to [Tom Preston-Werner](http://github.com/mojombo) for showing
352 me ctemplate and [Leah Culver](http://github.com/leah) for the name "Mustache."
353
fe2effe @defunkt README improvements
defunkt authored
354 Special thanks to [Magnus Holm](http://judofyr.net/) for all his
355 awesome work on Mustache's parser.
356
05bedeb @defunkt acknowledgements
defunkt authored
357
190b84d @defunkt project meta info in the readme (issue tracker, mailing list, etc)
defunkt authored
358 Meta
359 ----
141fa9a @defunkt partials docs
defunkt authored
360
190b84d @defunkt project meta info in the readme (issue tracker, mailing list, etc)
defunkt authored
361 * Code: `git clone git://github.com/defunkt/mustache.git`
dd5ced9 @defunkt more links in the readme
defunkt authored
362 * Home: <http://defunkt.github.com/mustache>
190b84d @defunkt project meta info in the readme (issue tracker, mailing list, etc)
defunkt authored
363 * Bugs: <http://github.com/defunkt/mustache/issues>
364 * List: <http://groups.google.com/group/mustache-rb>
ff3cb6d @defunkt add runcoderun link
defunkt authored
365 * Test: <http://runcoderun.com/defunkt/mustache>
dd5ced9 @defunkt more links in the readme
defunkt authored
366 * Gems: <http://rubygems.org/gems/mustache>
02edd2c @defunkt references make the first paragraph it read easier
defunkt authored
367
5340f4d @defunkt mention #{
defunkt authored
368 You can also find us in `#{` on irc.freenode.net.
369
02edd2c @defunkt references make the first paragraph it read easier
defunkt authored
370 [1]: http://code.google.com/p/google-ctemplate/
371 [2]: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
3e42d49 @defunkt document Set Delimiter
defunkt authored
372 [3]: http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
373 [4]: http://github.com/brynary/rack-bug/
e5ae462 @defunkt screenshot!
defunkt authored
374 [5]: http://img.skitch.com/20091027-n8pxwwx8r61tc318a15q1n6m14.png
Something went wrong with that request. Please try again.