Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 416 lines (274 sloc) 9.901 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
946b058 @defunkt new url
defunkt authored
11 <http://mustache.github.com/>.
dd5ced9 @defunkt more links in the readme
defunkt authored
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}}
0194a29 @defunkt Remove ${{blah}} from examples, too confusing
defunkt authored
78 You have just won {{value}} dollars!
3aad2f3 @defunkt docs
defunkt authored
79 {{#in_ca}}
0194a29 @defunkt Remove ${{blah}} from examples, too confusing
defunkt authored
80 Well, {{taxed_value}} dollars, after taxes.
3aad2f3 @defunkt docs
defunkt authored
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
0194a29 @defunkt Remove ${{blah}} from examples, too confusing
defunkt authored
91 You have just won 10000 dollars!
92 Well, 6000.0 dollars, after taxes.
3aad2f3 @defunkt docs
defunkt authored
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
946b058 @defunkt new url
defunkt authored
102 <http://mustache.github.com/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}}
0194a29 @defunkt Remove ${{blah}} from examples, too confusing
defunkt authored
128 You have just won {{value}} bucks!
04e852b @defunkt explain the dict style
defunkt authored
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
0194a29 @defunkt Remove ${{blah}} from examples, too confusing
defunkt authored
140 You have just won 100 bucks!
04e852b @defunkt explain the dict style
defunkt authored
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
0194a29 @defunkt Remove ${{blah}} from examples, too confusing
defunkt authored
147 You have just won 100 bucks!
04e852b @defunkt explain the dict style
defunkt authored
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
0c240e8 @defunkt Update gravatar example in README
defunkt authored
211 def gravatar
212 gravatar_id = Digest::MD5.hexdigest(self[:email].to_s.strip.downcase)
213 gravatar_for_id(gravatar_id)
70af848 @defunkt helpers?!
defunkt authored
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
0c240e8 @defunkt Update gravatar example in README
defunkt authored
245
246 def users
247 User.all
248 end
70af848 @defunkt helpers?!
defunkt authored
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
f0857e5 @defunkt rtemplate => mustache
defunkt authored
254 Here's on example which illustrates a key feature of Mustache: you
70af848 @defunkt helpers?!
defunkt authored
255 are free to use the `initialize` method just as you would in any
256 normal class.
257
f0857e5 @defunkt rtemplate => mustache
defunkt authored
258 class Simple < Mustache
70af848 @defunkt helpers?!
defunkt authored
259 include ViewHelpers
260
261 def initialize(ssl = false)
262 @ssl = ssl
263 end
264
265 ... etc ...
266 end
267
268 Now:
269
9b245dd @defunkt `render` is the new `to_html`
defunkt authored
270 Simple.new(request.ssl?).render
70af848 @defunkt helpers?!
defunkt authored
271
0c240e8 @defunkt Update gravatar example in README
defunkt authored
272 Finally, our template might look like this:
273
274 <ul>
275 {{# users}}
276 <li><img src="{{ gravatar }}"> {{ login }}</li>
277 {{/ users}}
278 </ul>
70af848 @defunkt helpers?!
defunkt authored
279
280
d7d6f66 @defunkt mention sinatra integration in README
defunkt authored
281 Sinatra
282 -------
283
284 Mustache ships with Sinatra integration. Please see
285 `lib/mustache/sinatra.rb` or
fe2effe @defunkt README improvements
defunkt authored
286 <http://github.com/defunkt/mustache/blob/master/lib/mustache/sinatra.rb>
287 for complete documentation.
d7d6f66 @defunkt mention sinatra integration in README
defunkt authored
288
ca40124 @defunkt reference the mustache-sinatra-example
defunkt authored
289 An example Sinatra application is also provided:
290 <http://github.com/defunkt/mustache-sinatra-example>
291
2db33e8 @defunkt upgrading
defunkt authored
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
d7d6f66 @defunkt mention sinatra integration in README
defunkt authored
299
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
300 [Rack::Bug][4]
4891479 @defunkt Added `mustache` script for rendering templates on the command line.
defunkt authored
301 --------------
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
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
e5ae462 @defunkt screenshot!
defunkt authored
314 [![Rack::Bug](http://img.skitch.com/20091027-xyf4h1yxnefpp7usyddrcmc7dn.png)][5]
315
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
316
da44c7e @defunkt Add mustache.vim [Juvenn Woo]
defunkt authored
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
dd5ced9 @defunkt more links in the readme
defunkt authored
323 See <http://gist.github.com/323622> for installation instructions.
da44c7e @defunkt Add mustache.vim [Juvenn Woo]
defunkt authored
324
fe2effe @defunkt README improvements
defunkt authored
325
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
326 Emacs
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
327 -----
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
328
b8ecafc @defunkt mustache.mode.el
defunkt authored
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.
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
333
dd5ced9 @defunkt more links in the readme
defunkt authored
334 See <http://gist.github.com/323619> for installation instructions.
335
13bd8ed @defunkt Added tpl-mode.el to contrib/ for us Emacs users
defunkt authored
336
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
337 TextMate
338 --------
339
dd5ced9 @defunkt more links in the readme
defunkt authored
340 [Mustache.tmbundle](http://github.com/defunkt/Mustache.tmbundle)
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
341
dd5ced9 @defunkt more links in the readme
defunkt authored
342 See <http://gist.github.com/323624> for installation instructions.
6f04090 @defunkt Mention Tekkub's Mustache TextMate bundle
defunkt authored
343
fe2effe @defunkt README improvements
defunkt authored
344
4891479 @defunkt Added `mustache` script for rendering templates on the command line.
defunkt authored
345 Command Line
346 ------------
347
dd5ced9 @defunkt more links in the readme
defunkt authored
348 See `mustache(1)` man page or
946b058 @defunkt new url
defunkt authored
349 <http://mustache.github.com/mustache.1.html>
dd5ced9 @defunkt more links in the readme
defunkt authored
350 for command line docs.
4891479 @defunkt Added `mustache` script for rendering templates on the command line.
defunkt authored
351
fe2effe @defunkt README improvements
defunkt authored
352
b6e396f @defunkt add installation and docs
defunkt authored
353 Installation
354 ------------
355
dd5ced9 @defunkt more links in the readme
defunkt authored
356 ### [RubyGems](http://rubygems.org/)
b6e396f @defunkt add installation and docs
defunkt authored
357
358 $ gem install mustache
d5258f3 @defunkt whitespace
defunkt authored
359
fe2effe @defunkt README improvements
defunkt authored
360
05bedeb @defunkt acknowledgements
defunkt authored
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
fe2effe @defunkt README improvements
defunkt authored
367 Special thanks to [Magnus Holm](http://judofyr.net/) for all his
368 awesome work on Mustache's parser.
369
05bedeb @defunkt acknowledgements
defunkt authored
370
7464499 @defunkt new mailing list, Contributing guidelines
defunkt authored
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
190b84d @defunkt project meta info in the readme (issue tracker, mailing list, etc)
defunkt authored
396 Meta
397 ----
141fa9a @defunkt partials docs
defunkt authored
398
190b84d @defunkt project meta info in the readme (issue tracker, mailing list, etc)
defunkt authored
399 * Code: `git clone git://github.com/defunkt/mustache.git`
946b058 @defunkt new url
defunkt authored
400 * Home: <http://mustache.github.com>
190b84d @defunkt project meta info in the readme (issue tracker, mailing list, etc)
defunkt authored
401 * Bugs: <http://github.com/defunkt/mustache/issues>
7464499 @defunkt new mailing list, Contributing guidelines
defunkt authored
402 * List: <mustache@librelist.com>
ff3cb6d @defunkt add runcoderun link
defunkt authored
403 * Test: <http://runcoderun.com/defunkt/mustache>
dd5ced9 @defunkt more links in the readme
defunkt authored
404 * Gems: <http://rubygems.org/gems/mustache>
02edd2c @defunkt references make the first paragraph it read easier
defunkt authored
405
5340f4d @defunkt mention #{
defunkt authored
406 You can also find us in `#{` on irc.freenode.net.
407
02edd2c @defunkt references make the first paragraph it read easier
defunkt authored
408 [1]: http://code.google.com/p/google-ctemplate/
409 [2]: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
3e42d49 @defunkt document Set Delimiter
defunkt authored
410 [3]: http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html
50ec6b7 @defunkt Added Rack::Bug panel
defunkt authored
411 [4]: http://github.com/brynary/rack-bug/
e5ae462 @defunkt screenshot!
defunkt authored
412 [5]: http://img.skitch.com/20091027-n8pxwwx8r61tc318a15q1n6m14.png
7464499 @defunkt new mailing list, Contributing guidelines
defunkt authored
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.