Skip to content
This repository
Newer
Older
100644 416 lines (274 sloc) 9.901 kb
f0857e5c »
2009-10-03 rtemplate => mustache
1 Mustache
6ee6bcf2 »
2009-09-24 first draft
2 =========
3
02edd2cf »
2009-10-10 references make the first paragraph it read easier
4 Inspired by [ctemplate][1] and [et][2], Mustache is a
5 framework-agnostic way to render logic-free views.
6ee6bcf2 »
2009-09-24 first draft
6
b32c566b »
2009-10-05 quote ctemplates
7 As ctemplates says, "It emphasizes separating logic from presentation:
8 it is impossible to embed application logic in this template language."
3aad2f34 »
2009-09-24 docs
9
dd5ced98 »
2010-03-06 more links in the readme
10 For a list of implementations (other than Ruby) and tips, see
946b0588 »
2010-03-31 new url
11 <http://mustache.github.com/>.
dd5ced98 »
2010-03-06 more links in the readme
12
0b217cfe »
2009-09-24 talk about tags first. they're important.
13
3aad2f34 »
2009-09-24 docs
14 Overview
15 --------
16
f0857e5c »
2009-10-03 rtemplate => mustache
17 Think of Mustache as a replacement for your views. Instead of views
3aad2f34 »
2009-09-24 docs
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
d5258f36 »
2009-10-06 whitespace
27 but reference methods in your view.
3aad2f34 »
2009-09-24 docs
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
0b217cfe »
2009-09-24 talk about tags first. they're important.
32
1d6dfeed »
2009-09-25 why?
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
3aad2f34 »
2009-09-24 docs
42 Usage
43 -----
44
debca50f »
2009-10-08 Quick example.
45 Quick example:
46
47 >> require 'mustache'
48 => true
49 >> Mustache.render("Hello {{planet}}", :planet => "World!")
50 => "Hello World!"
51
3aad2f34 »
2009-09-24 docs
52 We've got an `examples` folder but here's the canonical one:
53
f0857e5c »
2009-10-03 rtemplate => mustache
54 class Simple < Mustache
3aad2f34 »
2009-09-24 docs
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}}
0194a294 »
2010-04-18 Remove ${{blah}} from examples, too confusing
78 You have just won {{value}} dollars!
3aad2f34 »
2009-09-24 docs
79 {{#in_ca}}
0194a294 »
2010-04-18 Remove ${{blah}} from examples, too confusing
80 Well, {{taxed_value}} dollars, after taxes.
3aad2f34 »
2009-09-24 docs
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
9b245dd2 »
2009-10-10 `render` is the new `to_html`
86 Simple.render
3aad2f34 »
2009-09-24 docs
87
88 Which returns the following:
89
90 Hello Chris
0194a294 »
2010-04-18 Remove ${{blah}} from examples, too confusing
91 You have just won 10000 dollars!
92 Well, 6000.0 dollars, after taxes.
3aad2f34 »
2009-09-24 docs
93
94 Simple.
95
0b217cfe »
2009-09-24 talk about tags first. they're important.
96
97 Tag Types
98 ---------
99
dd5ced98 »
2010-03-06 more links in the readme
100 For a language-agnostic overview of Mustache's template syntax, see
101 the `mustache(5)` manpage or
946b0588 »
2010-03-31 new url
102 <http://mustache.github.com/mustache.5.html>.
3e42d49b »
2009-10-11 document Set Delimiter
103
104
6eb4df01 »
2010-03-06 steal Escaping section from mustache.js
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
04e852b2 »
2009-09-24 explain the dict style
118 Dict-Style Views
119 ----------------
120
121 ctemplate and friends want you to hand a dictionary to the template
515de916 »
2009-10-11 Dict example uses Winner to be more explicit, less confusing
122 processor. Mustache supports a similar concept. Feel free to mix the
123 class-based and this more procedural style at your leisure.
04e852b2 »
2009-09-24 explain the dict style
124
07144e45 »
2009-10-27 Update readme with .html => .mustache change
125 Given this template (winner.mustache):
04e852b2 »
2009-09-24 explain the dict style
126
127 Hello {{name}}
0194a294 »
2010-04-18 Remove ${{blah}} from examples, too confusing
128 You have just won {{value}} bucks!
04e852b2 »
2009-09-24 explain the dict style
129
130 We can fill in the values at will:
d5258f36 »
2009-10-06 whitespace
131
515de916 »
2009-10-11 Dict example uses Winner to be more explicit, less confusing
132 view = Winner.new
133 view[:name] = 'George'
134 view[:value] = 100
135 view.render
04e852b2 »
2009-09-24 explain the dict style
136
137 Which returns:
d5258f36 »
2009-10-06 whitespace
138
04e852b2 »
2009-09-24 explain the dict style
139 Hello George
0194a294 »
2010-04-18 Remove ${{blah}} from examples, too confusing
140 You have just won 100 bucks!
04e852b2 »
2009-09-24 explain the dict style
141
142 We can re-use the same object, too:
143
515de916 »
2009-10-11 Dict example uses Winner to be more explicit, less confusing
144 view[:name] = 'Tony'
145 view.render
04e852b2 »
2009-09-24 explain the dict style
146 Hello Tony
0194a294 »
2010-04-18 Remove ${{blah}} from examples, too confusing
147 You have just won 100 bucks!
04e852b2 »
2009-09-24 explain the dict style
148
0b217cfe »
2009-09-24 talk about tags first. they're important.
149
671f6aa3 »
2009-09-24 document template options and make template_file configurable
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
07144e45 »
2009-10-27 Update readme with .html => .mustache change
157 TemplatePartial => ./template_partial.mustache
d5258f36 »
2009-10-06 whitespace
158
3291a2d7 »
2009-10-11 document template_extension in the README
159 You can set the search path using `Mustache.template_path`. It can be set on a
671f6aa3 »
2009-09-24 document template options and make template_file configurable
160 class by class basis:
161
f0857e5c »
2009-10-03 rtemplate => mustache
162 class Simple < Mustache
3291a2d7 »
2009-10-11 document template_extension in the README
163 self.template_path = File.dirname(__FILE__)
671f6aa3 »
2009-09-24 document template options and make template_file configurable
164 ... etc ...
165 end
166
07144e45 »
2009-10-27 Update readme with .html => .mustache change
167 Now `Simple` will look for `simple.mustache` in the directory it resides
671f6aa3 »
2009-09-24 document template options and make template_file configurable
168 in, no matter the cwd.
169
170 If you want to just change what template is used you can set
5b3b4c34 »
2009-10-05 Compile into a Proc (for speed). This required more changes:
171 `Mustache.template_file` directly:
671f6aa3 »
2009-09-24 document template options and make template_file configurable
172
07144e45 »
2009-10-27 Update readme with .html => .mustache change
173 Simple.template_file = './blah.mustache'
d5258f36 »
2009-10-06 whitespace
174
3291a2d7 »
2009-10-11 document template_extension in the README
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:
671f6aa3 »
2009-09-24 document template options and make template_file configurable
183
5b3b4c34 »
2009-10-05 Compile into a Proc (for speed). This required more changes:
184 Simple.template = 'Hi {{person}}!'
185
3291a2d7 »
2009-10-11 document template_extension in the README
186 Or set a different template for a single instance:
5b3b4c34 »
2009-10-05 Compile into a Proc (for speed). This required more changes:
187
671f6aa3 »
2009-09-24 document template options and make template_file configurable
188 Simple.new.template = 'Hi {{person}}!'
189
190 Whatever works.
191
0b217cfe »
2009-09-24 talk about tags first. they're important.
192
40313b95 »
2009-10-27 Added autoloading
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
70af848e »
2009-09-24 helpers?!
202 Helpers
203 -------
204
205 What about global helpers? Maybe you have a nifty `gravatar` function
d5258f36 »
2009-10-06 whitespace
206 you want to use in all your views? No problem.
70af848e »
2009-09-24 helpers?!
207
208 This is just Ruby, after all.
209
210 module ViewHelpers
0c240e87 »
2010-10-08 Update gravatar example in README
211 def gravatar
212 gravatar_id = Digest::MD5.hexdigest(self[:email].to_s.strip.downcase)
213 gravatar_for_id(gravatar_id)
70af848e »
2009-09-24 helpers?!
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
d5258f36 »
2009-10-06 whitespace
225 Then just include it:
70af848e »
2009-09-24 helpers?!
226
f0857e5c »
2009-10-03 rtemplate => mustache
227 class Simple < Mustache
70af848e »
2009-09-24 helpers?!
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
0c240e87 »
2010-10-08 Update gravatar example in README
245
246 def users
247 User.all
248 end
70af848e »
2009-09-24 helpers?!
249 end
250
251 Great, but what about that `@ssl` ivar in `gravatar_host`? There are
252 many ways we can go about setting it.
253
f0857e5c »
2009-10-03 rtemplate => mustache
254 Here's on example which illustrates a key feature of Mustache: you
70af848e »
2009-09-24 helpers?!
255 are free to use the `initialize` method just as you would in any
256 normal class.
257
f0857e5c »
2009-10-03 rtemplate => mustache
258 class Simple < Mustache
70af848e »
2009-09-24 helpers?!
259 include ViewHelpers
260
261 def initialize(ssl = false)
262 @ssl = ssl
263 end
264
265 ... etc ...
266 end
267
268 Now:
269
9b245dd2 »
2009-10-10 `render` is the new `to_html`
270 Simple.new(request.ssl?).render
70af848e »
2009-09-24 helpers?!
271
0c240e87 »
2010-10-08 Update gravatar example in README
272 Finally, our template might look like this:
273
274 <ul>
275 {{# users}}
276 <li><img src="{{ gravatar }}"> {{ login }}</li>
277 {{/ users}}
278 </ul>
70af848e »
2009-09-24 helpers?!
279
280
d7d6f662 »
2009-10-08 mention sinatra integration in README
281 Sinatra
282 -------
283
284 Mustache ships with Sinatra integration. Please see
285 `lib/mustache/sinatra.rb` or
fe2effeb »
2010-03-26 README improvements
286 <http://github.com/defunkt/mustache/blob/master/lib/mustache/sinatra.rb>
287 for complete documentation.
d7d6f662 »
2009-10-08 mention sinatra integration in README
288
ca401249 »
2009-10-09 reference the mustache-sinatra-example
289 An example Sinatra application is also provided:
290 <http://github.com/defunkt/mustache-sinatra-example>
291
2db33e83 »
2010-03-26 upgrading
292 If you are upgrading to Sinatra 1.0 and Mustache 0.9.0+ from Mustache
293 0.7.0 or lower, the settings have changed. But not that much.
294
295 See [this diff](http://gist.github.com/345490) for what you need to
296 do. Basically, things are named properly now and all should be
297 contained in a hash set using `set :mustache, hash`.
298
d7d6f662 »
2009-10-08 mention sinatra integration in README
299
50ec6b7a »
2009-10-27 Added Rack::Bug panel
300 [Rack::Bug][4]
48914790 »
2009-11-23 Added `mustache` script for rendering templates on the command line.
301 --------------
50ec6b7a »
2009-10-27 Added Rack::Bug panel
302
303 Mustache also ships with a `Rack::Bug` panel. In your `config.ru` add
304 the following code:
305
306 require 'rack/bug/panels/mustache_panel'
307 use Rack::Bug::MustachePanel
308
309 Using Rails? Add this to your initializer or environment file:
310
311 require 'rack/bug/panels/mustache_panel'
312 config.middleware.use "Rack::Bug::MustachePanel"
313
e5ae4624 »
2009-10-27 screenshot!
314 [![Rack::Bug](http://img.skitch.com/20091027-xyf4h1yxnefpp7usyddrcmc7dn.png)][5]
315
50ec6b7a »
2009-10-27 Added Rack::Bug panel
316
da44c7e3 »
2009-10-16 Add mustache.vim [Juvenn Woo]
317 Vim
318 ---
319
320 Thanks to [Juvenn Woo](http://github.com/juvenn) for mustache.vim. It
321 is included under the contrib/ directory.
322
dd5ced98 »
2010-03-06 more links in the readme
323 See <http://gist.github.com/323622> for installation instructions.
da44c7e3 »
2009-10-16 Add mustache.vim [Juvenn Woo]
324
fe2effeb »
2010-03-26 README improvements
325
13bd8ed4 »
2009-10-27 Added tpl-mode.el to contrib/ for us Emacs users
326 Emacs
6f04090d »
2009-11-12 Mention Tekkub's Mustache TextMate bundle
327 -----
13bd8ed4 »
2009-10-27 Added tpl-mode.el to contrib/ for us Emacs users
328
b8ecafcd »
2010-03-06 mustache.mode.el
329 mustache-mode.el is included under the contrib/ directory for any
330 Emacs users. Based on Google's tpl-mode for ctemplates, it adds
331 support for Mustache's more lenient tag values and includes a few
332 commands for your editing pleasure.
13bd8ed4 »
2009-10-27 Added tpl-mode.el to contrib/ for us Emacs users
333
dd5ced98 »
2010-03-06 more links in the readme
334 See <http://gist.github.com/323619> for installation instructions.
335
13bd8ed4 »
2009-10-27 Added tpl-mode.el to contrib/ for us Emacs users
336
6f04090d »
2009-11-12 Mention Tekkub's Mustache TextMate bundle
337 TextMate
338 --------
339
dd5ced98 »
2010-03-06 more links in the readme
340 [Mustache.tmbundle](http://github.com/defunkt/Mustache.tmbundle)
6f04090d »
2009-11-12 Mention Tekkub's Mustache TextMate bundle
341
dd5ced98 »
2010-03-06 more links in the readme
342 See <http://gist.github.com/323624> for installation instructions.
6f04090d »
2009-11-12 Mention Tekkub's Mustache TextMate bundle
343
fe2effeb »
2010-03-26 README improvements
344
48914790 »
2009-11-23 Added `mustache` script for rendering templates on the command line.
345 Command Line
346 ------------
347
dd5ced98 »
2010-03-06 more links in the readme
348 See `mustache(1)` man page or
946b0588 »
2010-03-31 new url
349 <http://mustache.github.com/mustache.1.html>
dd5ced98 »
2010-03-06 more links in the readme
350 for command line docs.
48914790 »
2009-11-23 Added `mustache` script for rendering templates on the command line.
351
fe2effeb »
2010-03-26 README improvements
352
b6e396fc »
2009-10-05 add installation and docs
353 Installation
354 ------------
355
dd5ced98 »
2010-03-06 more links in the readme
356 ### [RubyGems](http://rubygems.org/)
b6e396fc »
2009-10-05 add installation and docs
357
358 $ gem install mustache
d5258f36 »
2009-10-06 whitespace
359
fe2effeb »
2010-03-26 README improvements
360
05bedebb »
2009-10-06 acknowledgements
361 Acknowledgements
362 ----------------
363
364 Thanks to [Tom Preston-Werner](http://github.com/mojombo) for showing
365 me ctemplate and [Leah Culver](http://github.com/leah) for the name "Mustache."
366
fe2effeb »
2010-03-26 README improvements
367 Special thanks to [Magnus Holm](http://judofyr.net/) for all his
368 awesome work on Mustache's parser.
369
05bedebb »
2009-10-06 acknowledgements
370
7464499d »
2010-03-31 new mailing list, Contributing guidelines
371 Contributing
372 ------------
373
374 Once you've made your great commits:
375
376 1. [Fork][fk] Mustache
377 2. Create a topic branch - `git checkout -b my_branch`
378 3. Push to your branch - `git push origin my_branch`
379 4. Create an [Issue][is] with a link to your branch
380 5. That's it!
381
382 You might want to checkout Resque's [Contributing][cb] wiki page for information
383 on coding standards, new features, etc.
384
385
386 Mailing List
387 ------------
388
389 To join the list simply send an email to <mustache@librelist.com>. This
390 will subscribe you and send you information about your subscription,
391 including unsubscribe information.
392
393 The archive can be found at <http://librelist.com/browser/>.
394
395
190b84d7 »
2009-10-04 project meta info in the readme (issue tracker, mailing list, etc)
396 Meta
397 ----
141fa9ad »
2009-09-24 partials docs
398
190b84d7 »
2009-10-04 project meta info in the readme (issue tracker, mailing list, etc)
399 * Code: `git clone git://github.com/defunkt/mustache.git`
946b0588 »
2010-03-31 new url
400 * Home: <http://mustache.github.com>
190b84d7 »
2009-10-04 project meta info in the readme (issue tracker, mailing list, etc)
401 * Bugs: <http://github.com/defunkt/mustache/issues>
7464499d »
2010-03-31 new mailing list, Contributing guidelines
402 * List: <mustache@librelist.com>
ff3cb6d9 »
2009-10-04 add runcoderun link
403 * Test: <http://runcoderun.com/defunkt/mustache>
dd5ced98 »
2010-03-06 more links in the readme
404 * Gems: <http://rubygems.org/gems/mustache>
02edd2cf »
2009-10-10 references make the first paragraph it read easier
405
5340f4d0 »
2010-03-09 mention #{
406 You can also find us in `#{` on irc.freenode.net.
407
02edd2cf »
2009-10-10 references make the first paragraph it read easier
408 [1]: http://code.google.com/p/google-ctemplate/
409 [2]: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
3e42d49b »
2009-10-11 document Set Delimiter
410 [3]: http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html
50ec6b7a »
2009-10-27 Added Rack::Bug panel
411 [4]: http://github.com/brynary/rack-bug/
e5ae4624 »
2009-10-27 screenshot!
412 [5]: http://img.skitch.com/20091027-n8pxwwx8r61tc318a15q1n6m14.png
7464499d »
2010-03-31 new mailing list, Contributing guidelines
413 [cb]: http://wiki.github.com/defunkt/resque/contributing
414 [fk]: http://help.github.com/forking/
415 [is]: http://github.com/defunkt/mustache/issues
Something went wrong with that request. Please try again.