Skip to content
Newer
Older
100644 408 lines (268 sloc) 11.1 KB
61eee29 @tj Started readme
tj authored Jun 30, 2010
1
2 # Jade - template engine
3
2849e11 @tj Added features
tj authored Jun 30, 2010
4 Jade is a high performance template engine heavily influenced by [Haml](http://haml-lang.com)
5 and implemented with JavaScript for [node](http://nodejs.org).
6
7 ## Features
8
9 - high performance parser
10 - great readability
11 - code is escaped by default for security
12 - contextual error reporting at compile & run time
690f915 @tj More features
tj authored Jun 30, 2010
13 - executable for compiling jade templates via the command line
14 - html 5 mode (using the _!!! 5_ doctype)
15 - optional memory caching
e104867 @tj Filter docs
tj authored Jun 30, 2010
16 - combine dynamic and static tag classes
51e4dda @tj Quick docs for filters with the parse tree
tj authored Sep 23, 2010
17 - parse tree manipulation via _filters_
18 - supports [Express JS](http://expressjs.com) out of the box
77fa5ca @tj Added -each docs
tj authored Jul 8, 2010
19 - transparent iteration over objects, arrays, and even non-enumerables via `- each`
2849e11 @tj Added features
tj authored Jul 1, 2010
20 - no tag prefix
21 - filters
edc190b @tj Fixed markdown support
tj authored Jul 8, 2010
22 - :sass must have [sass.js](http://github.com/visionmedia/sass.js) installed
23 - :less must have [less.js](http://github.com/cloudhead/less.js) installed
efafcfe @tj Added node-discount in readme
tj authored Jul 9, 2010
24 - :markdown must have [markdown-js](http://github.com/evilstreak/markdown-js) installed or [node-discount](http://github.com/visionmedia/node-discount)
2849e11 @tj Added features
tj authored Jul 1, 2010
25 - :cdata
26 - :javascript
be87cb9 @mirhampt Add coffeescript filter
mirhampt authored Oct 19, 2010
27 - :coffeescript must have [coffee-script](http://jashkenas.github.com/coffee-script/) installed
5428d8c @tj Added link to vim-jade
tj authored Jan 4, 2011
28 - [Vim Syntax](https://github.com/digitaltoad/vim-jade)
0accfe7 @tj Added link to textmate bundle
tj authored Jul 16, 2010
29 - [TextMate Bundle](http://github.com/miksago/jade-tmbundle)
1d46c1d @tj Added screencasts link
tj authored Aug 24, 2010
30 - [Screencasts](http://tjholowaychuk.com/post/1004255394/jade-screencast-template-engine-for-nodejs)
2849e11 @tj Added features
tj authored Jul 1, 2010
31
dcbc04f @tj Implementations section
tj authored Jul 27, 2010
32 ## Implementations
33
a74428a @tj Changed jade.php link
tj authored Jul 27, 2010
34 - [php](http://github.com/everzet/jade.php)
12b44db @tj Added scala link
tj authored Aug 2, 2010
35 - [scala](http://scalate.fusesource.org/versions/snapshot/documentation/scaml-reference.html)
6a0b814 @tj Added link to "slim" a ruby implementation
tj authored Oct 26, 2010
36 - [ruby](http://github.com/stonean/slim)
dcbc04f @tj Implementations section
tj authored Jul 27, 2010
37
a9a5fd5 @tj Added install docs / seed.yml
tj authored Jul 1, 2010
38 ## Installation
39
40 via npm:
41
42 npm install jade
43
7ece7e6 @tj Public api docs
tj authored Jun 30, 2010
44 ## Public API
45
46 var jade = require('jade');
47
48 // Render a string
49 jade.render('string of jade', { options: 'here' });
50
51 // Render a file
52 jade.renderFile('path/to/some.jade', { options: 'here' }, function(err, html){
53 // options are optional,
54 // the callback can be the second arg
55 });
56
77b3264 @tj Docs for render()
tj authored Jun 30, 2010
57 ### Options
58
59 - `scope` Evaluation scope (`this`)
60 - `locals` Local variable object
61 - `filename` Used in exceptions, and required by `cache`
62 - `cache` Cache intermediate JavaScript in memory keyed by `filename`
f57202e @tj Added debug option to readme
tj authored Jul 1, 2010
63 - `debug` Outputs tokens and function body generated
261c844 @tj Added pretty to readme
tj authored Sep 11, 2010
64 - `compiler` Compiler to replace jade's default
77b3264 @tj Docs for render()
tj authored Jul 1, 2010
65
39ca646 @tj More docs
tj authored Jun 30, 2010
66 ## Syntax
67
68 ### Line Endings
69
6c2333b @tj Doc typo
tj authored Jun 30, 2010
70 **CRLF** and **CR** are converted to **LF** before parsing.
39ca646 @tj More docs
tj authored Jul 1, 2010
71
72 ### Indentation
73
74 Jade is indentation based, however currently only supports a _2 space_ indent.
e9d1c83 @tj Removed profanity from the readme :). Closes #101
tj authored Oct 15, 2010
75 Tabs are converted to 2 spaces before they hit the lexer.
39ca646 @tj More docs
tj authored Jul 1, 2010
76
8c6488f @tj Tag docs
tj authored Jun 30, 2010
77 ### Tags
78
79 A tag is simply a leading word:
80
81 html
82
83 for example is converted to `<html></html>`
84
f61bf53 @tj More tag docs
tj authored Jun 30, 2010
85 tags can also have ids:
86
87 div#container
88
89 which would render `<div id="container"></div>`
90
91 how about some classes?
92
93 div.user-details
94
95 renders `<div class="user-details"></div>`
96
97 multiple classes? _and_ an id? sure:
98
99 div#foo.bar.baz
100
101 renders `<div id="foo" class="bar baz"></div>`
102
103 div div div sure is annoying, how about:
104
105 #foo
106 .bar
107
108 which is syntactic sugar for what we have already been doing, and outputs:
109
110 `<div id="foo"></div><div class="bar"></div>`
111
346bda8 @tj Tag text docs
tj authored Jun 30, 2010
112 ### Tag Text
113
114 Simply place some content after the tag:
115
116 p wahoo!
90e0ebd @tj Added interpolation docs
tj authored Jun 30, 2010
117
118 renders `<p>wahoo!</p>`.
119
120 well cool, but how about large bodies of text:
121
122 p
123 | foo bar baz
124 | rawr rawr
125 | super cool
126 | go jade go
127
128 renders `<p>foo bar baz rawr.....</p>`
129
130 interpolation? yup! both types of text can utilize interpolation,
131 if we passed `{ locals: { name: 'tj', email: 'tj@vision-media.ca' }}` to `render()`
132 we can do the following:
133
134 #user #{name} &lt;#{email}&gt;
135
136 outputs `<div id="user">tj &lt;tj@vision-media.ca&gt;</div>`
346bda8 @tj Tag text docs
tj authored Jul 1, 2010
137
01f4f62 @tj Interpolation escape docs
tj authored Jun 30, 2010
138 Actually want `#{}` for some reason? escape it!
139
140 p \#{something}
141
142 now we have `<p>#{something}</p>`
143
ec6fc45 @tj Docs
tj authored Dec 19, 2010
144 We can also utilize the unescaped variant `!{html}`, so the following
145 will result in a literal script tag:
146
147 - var html = "<script></script>"
148 | !{html}
149
a6ed2c7 @tj Tag text docs
tj authored Oct 5, 2010
150 Nested tags that also contain text can optionally use a text block:
151
152 label
153 | Username:
154 input(name='user[name]')
155
156 or immediate tag text:
157
158 label Username:
159 input(name='user[name]')
160
bc1d8f9 @tj Added single line comment support. Closes #25
tj authored Aug 4, 2010
161 ### Comments
162
163 Single line comments currently look the same as JavaScript comments,
164 aka "//" and must be placed on their own line:
165
166 // just some paragraphs
167 p foo
168 p bar
169
170 would output
171
172 <!-- just some paragraphs -->
173 <p>foo</p>
174 <p>bar</p>
175
320a427 @tj Added unbuffered comment support. Closes #62
tj authored Aug 30, 2010
176 Jade also supports unbuffered comments, by simply adding a hyphen:
177
178 //- will not output within markup
179 p foo
180 p bar
181
182 outputting
183
184 <p>foo</p>
185 <p>bar</p>
186
39ca646 @tj More docs
tj authored Jul 1, 2010
187 ### Nesting
188
189 ul
190 li one
191 li two
192 li three
193
e9d1c83 @tj Removed profanity from the readme :). Closes #101
tj authored Oct 15, 2010
194 Messed up your whitespace? no worries, jade's error reporting should help you out.
a0ee2c0 @tj More docs
tj authored Jul 1, 2010
195 Jade instruments the compiled JavaScript to provide meaningful context for runtime exceptions.
39ca646 @tj More docs
tj authored Jul 1, 2010
196
197 ul
198 li one
199 li two
200
201 Error: /Users/tj/Projects/jade/examples/layout.jade:2
202 1. 'ul'
203 2. ' li one'
204
205 Invalid indentation, got 2 expected 1.
206
aecf8c6 @tj Doc typos
tj authored Oct 5, 2010
207 Note: Trailing outdents are generated on **EOS** (end-of-source) if not present.
39ca646 @tj More docs
tj authored Jul 1, 2010
208
209 ### Attributes
210
211 Jade currently supports '(' and ')' as attribute delimiters.
212
213 a(href='/login', title='View login page') Login
214
215 Alternatively we may use the colon to separate pairs:
216
217 a(href: '/login', title: 'View login page') Login
218
58ed759 @tj Doctypes
tj authored Jun 30, 2010
219 Boolean attributes are also supported:
220
221 input(type="checkbox", checked)
222
223 Boolean attributes with code will only output the attribute when `true`:
224
225 input(type="checkbox", checked: someValue)
226
aecf8c6 @tj Doc typos
tj authored Oct 5, 2010
227 Note: Leading / trailing whitespace is _ignored_ for attr pairs.
39ca646 @tj More docs
tj authored Jul 1, 2010
228
58ed759 @tj Doctypes
tj authored Jul 1, 2010
229 ### Doctypes
230
231 To add a doctype simply use `!!!` followed by an optional value:
232
233 !!!
234
235 Will output the _transitional_ doctype, however:
236
237 !!! 5
238
239 Will output html 5's doctype. Below are the doctypes
240 defined by default, which can easily be extended:
241 var doctypes = exports.doctypes = {
242 '5': '<!DOCTYPE html>',
243 'xml': '<?xml version="1.0" encoding="utf-8" ?>',
244 'default': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
245 'transitional': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
246 'strict': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
247 'frameset': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
248 '1.1': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
249 'basic': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">',
250 'mobile': '<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">'
251 };
252
f168fb8 @tj Added docs for changing default doctype
tj authored Jul 1, 2010
253 To alter the default simply change:
254
255 jade.doctypes.default = 'whatever you want';
256
e104867 @tj Filter docs
tj authored Jul 1, 2010
257 ## Filters
258
259 Filters are prefixed with `:`, for example `:markdown` and
260 pass the following block of text to an arbitrary function for processing. View the _features_
261 at the top of this document for available filters.
262
263 body
264 :markdown
265 | Woah! jade _and_ markdown, very **cool**
266 | we can even link to [stuff](http://google.com)
267
268 Renders:
269
270 <body><p>Woah! jade <em>and</em> markdown, very <strong>cool</strong> we can even link to <a href="http://google.com">stuff</a></p></body>
271
51e4dda @tj Quick docs for filters with the parse tree
tj authored Sep 23, 2010
272 Filters may also now manipulate the parse tree. For example perhaps I want to
273 bake conditionals right into jade, we could do so with a filter named _conditionals_. Typically filters work on text blocks, however by passing a regular block our filter can do anything it wants with the tags nested within it.
274
275 body
276 :conditionals
277 if role == 'admin'
278 p You are amazing
279 else
280 p Not so amazing
281
a6ed2c7 @tj Tag text docs
tj authored Oct 5, 2010
282 Not that we no longer prefix with "-" for these code blocks. Examples of
283 how to manipulate the parse tree can be found at _./examples/conditionals.js_ and _./examples/model.js_. There are several interesting use-cases for this functionality above what was shown above such as transparently aggregating / compressing assets to reduce the number of HTTP requests, transparent record error reporting, and more.
51e4dda @tj Quick docs for filters with the parse tree
tj authored Sep 23, 2010
284
dedd519 @tj Code docs
tj authored Jun 30, 2010
285 ## Code
286
287 Jade currently supports three classifications of executable code. The first
288 is prefixed by `-`, and is not buffered:
289
290 - var foo = 'bar';
291
292 This can be used for conditionals, or iteration:
293
294 - for (var key in obj)
295 p= obj[key]
296
297 Due to Jade's buffering techniques the following is valid as well:
298
299 - if (foo)
300 ul
301 li yay
302 li foo
303 li worked
304 - else
e9d1c83 @tj Removed profanity from the readme :). Closes #101
tj authored Oct 15, 2010
305 p oh no! didnt work
dedd519 @tj Code docs
tj authored Jul 1, 2010
306
13b2346 @tj Typo in docs
tj authored Jul 1, 2010
307 Hell, even verbose iteration:
dedd519 @tj Code docs
tj authored Jul 1, 2010
308
309 - if (items.length)
310 ul
311 - items.forEach(function(item){
0978059 @tj Fixed readme
tj authored Sep 11, 2010
312 li= item
313 - })
dedd519 @tj Code docs
tj authored Jul 1, 2010
314
315 Anything you want!
316
317 Next up we have _escaped_ buffered code, which is used to
318 buffer a return value, which is prefixed by `=`:
319
320 - var foo = 'bar'
321 = foo
322 h1= foo
323
324 Which outputs `bar<h1>bar<h1/>`. Code buffered by `=` is escaped
325 by default for security, however to output unescaped return values
326 you may use `!=`:
327
328 p!= aVarContainingMoreHTML
329
77fa5ca @tj Added -each docs
tj authored Jul 8, 2010
330 The on exception made in terms of allowing "vanilla" JavaScript, is
331 the `- each` token. This takes the form of:
332
333 - each VAL[, KEY] in OBJ
334
335 An example iterating over an array:
336
337 - var items = ["one", "two", "three"]
338 - each item in items
339 li= item
340
341 outputs:
342
343 <li>one</li>
344 <li>two</li>
345 <li>three</li>
346
347 iterating an object's keys and values:
348
349 - var obj = { foo: 'bar' }
350 - each val, key in obj
351 li #{key}: #{val}
352
353 would output `<li>foo: bar</li>`
354
355 You can also nest these!
356
357 - each user in users
358 - each role in user.roles
359 li= role
360
61eee29 @tj Started readme
tj authored Jul 1, 2010
361 ## bin/jade
362
363 Output html to _stdout_:
364
365 jade examples/*.jade --pipe
366
367 Generate _examples/*.html_:
368
369 jade examples/*.jade
370
371 Pass options:
372
373 jade examples/layout.jade --options '{ locals: { title: "foo" }}'
374
375 Usage info:
376
377 Usage: jade [options] <path ...>
378
379 Options:
380 -o, --options STR JavaScript options object passed
381 -p, --pipe Output to stdout instead of PATH.html
382 -h, --help Output help information
383
417edbf @tj License
tj authored Sep 13, 2010
384 ## License
385
386 (The MIT License)
387
388 Copyright (c) 2009-2010 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
389
390 Permission is hereby granted, free of charge, to any person obtaining
391 a copy of this software and associated documentation files (the
392 'Software'), to deal in the Software without restriction, including
393 without limitation the rights to use, copy, modify, merge, publish,
394 distribute, sublicense, and/or sell copies of the Software, and to
395 permit persons to whom the Software is furnished to do so, subject to
396 the following conditions:
397
398 The above copyright notice and this permission notice shall be
399 included in all copies or substantial portions of the Software.
400
401 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
402 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
403 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
404 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
405 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
406 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
407 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.