node_modules/jade/Readme.md

   1
   2 # Jade - template engine
   3
   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   - client-side support
  10   - great readability
  11   - flexible indentation
  12   - block-expansion
  13   - mixins
  14   - static includes
  15   - attribute interpolation
  16   - code is escaped by default for security
  17   - contextual error reporting at compile &amp; run time
  18   - executable for compiling jade templates via the command line
  19   - html 5 mode (using the _!!! 5_ doctype)
  20   - optional memory caching
  21   - combine dynamic and static tag classes
  22   - parse tree manipulation via _filters_
  23   - supports [Express JS](http://expressjs.com) out of the box
  24   - transparent iteration over objects, arrays, and even non-enumerables via `- each`
  25   - block comments
  26   - no tag prefix
  27   - AST filters
  28   - filters
  29     - :sass must have [sass.js](http://github.com/visionmedia/sass.js) installed
  30     - :less must have [less.js](http://github.com/cloudhead/less.js) installed
  31     - :markdown must have [markdown-js](http://github.com/evilstreak/markdown-js) installed or [node-discount](http://github.com/visionmedia/node-discount)
  32     - :cdata
  33     - :coffeescript must have [coffee-script](http://jashkenas.github.com/coffee-script/) installed
  34   - [Vim Syntax](https://github.com/digitaltoad/vim-jade)
  35   - [TextMate Bundle](http://github.com/miksago/jade-tmbundle)
  36   - [Screencasts](http://tjholowaychuk.com/post/1004255394/jade-screencast-template-engine-for-nodejs)
  37   - [html2jade](https://github.com/donpark/html2jade) converter
  38
  39 ## Implementations
  40
  41   - [php](http://github.com/everzet/jade.php)
  42   - [scala](http://scalate.fusesource.org/versions/snapshot/documentation/scaml-reference.html)
  43   - [ruby](http://github.com/stonean/slim)
  44
  45 ## Installation
  46
  47 via npm:
  48
  49     npm install jade
  50
  51 ## Browser Support
  52
  53  To compile jade to a single file compatible for client-side use simply execute:
  54
  55     $ make jade.js
  56
  57  Alternatively, if uglifyjs is installed via npm (`npm install uglify-js`) you may execute the following which will create both files.
  58
  59     $ make jade.min.js
  60
  61 ## Public API
  62
  63 ```javascript
  64     var jade = require('jade');
  65
  66     // Render a string
  67     jade.render('string of jade', { options: 'here' });
  68
  69     // Render a file
  70     jade.renderFile('path/to/some.jade', { options: 'here' }, function(err, html){
  71             // options are optional,
  72             // the callback can be the second arg
  73     });
  74
  75     // Compile a function
  76     var fn = jade.compile('string of jade', options);
  77     fn.call(scope, locals);
  78 ```
  79
  80 ### Options
  81
  82  - `scope`     Evaluation scope (`this`)
  83  - `self`      Use a `self` namespace to hold the locals. _false by default_
  84  - `locals`    Local variable object
  85  - `filename`  Used in exceptions, and required when using includes
  86  - `debug`     Outputs tokens and function body generated
  87  - `compiler`  Compiler to replace jade's default
  88
  89 ## Syntax
  90
  91 ### Line Endings
  92
  93 **CRLF** and **CR** are converted to **LF** before parsing.
  94
  95 ### Tags
  96
  97 A tag is simply a leading word:
  98
  99     html
 100
 101 for example is converted to `<html></html>`
 102
 103 tags can also have ids:
 104
 105     div#container
 106
 107 which would render `<div id="container"></div>`
 108
 109 how about some classes?
 110
 111     div.user-details
 112
 113 renders `<div class="user-details"></div>`
 114
 115 multiple classes? _and_ an id? sure:
 116
 117     div#foo.bar.baz
 118
 119 renders `<div id="foo" class="bar baz"></div>`
 120
 121 div div div sure is annoying, how about:
 122
 123     #foo
 124     .bar
 125
 126 which is syntactic sugar for what we have already been doing, and outputs:
 127
 128     `<div id="foo"></div><div class="bar"></div>`
 129
 130 ### Tag Text
 131
 132 Simply place some content after the tag:
 133
 134     p wahoo!
 135
 136 renders `<p>wahoo!</p>`.
 137
 138 well cool, but how about large bodies of text:
 139
 140     p
 141       | foo bar baz
 142       | rawr rawr
 143       | super cool
 144       | go jade go
 145
 146 renders `<p>foo bar baz rawr.....</p>`
 147
 148 interpolation? yup! both types of text can utilize interpolation,
 149 if we passed `{ locals: { name: 'tj', email: 'tj@vision-media.ca' }}` to `render()`
 150 we can do the following:
 151
 152     #user #{name} &lt;#{email}&gt;
 153
 154 outputs `<div id="user">tj &lt;tj@vision-media.ca&gt;</div>`
 155
 156 Actually want `#{}` for some reason? escape it!
 157
 158     p \#{something}
 159
 160 now we have `<p>#{something}</p>`
 161
 162 We can also utilize the unescaped variant `!{html}`, so the following
 163 will result in a literal script tag:
 164
 165     - var html = "<script></script>"
 166     | !{html}
 167
 168 Nested tags that also contain text can optionally use a text block:
 169
 170     label
 171       | Username:
 172       input(name='user[name]')
 173
 174 or immediate tag text:
 175
 176     label Username:
 177       input(name='user[name]')
 178
 179 Tags that accept _only_ text such as `script`, `style`, and `textarea` do not
 180 need the leading `|` character, for example:
 181
 182       html
 183         head
 184           title Example
 185           script
 186             if (foo) {
 187               bar();
 188             } else {
 189               baz();
 190             }
 191
 192 Once again as an alternative, we may use a leading '.' to indicate a text block, for example:
 193
 194       p.
 195         foo asdf
 196         asdf
 197          asdfasdfaf
 198          asdf
 199         asd.
 200
 201 outputs:
 202
 203         <p>foo asdf
 204         asdf
 205           asdfasdfaf
 206           asdf
 207         asd
 208         .
 209         </p>
 210
 211 This however differs from a leading '.' followed by a space, which although is ignored by the Jade parser, tells Jade that this period is a literal:
 212
 213     p .
 214
 215 outputs:
 216
 217     <p>.</p>
 218
 219 ### Comments
 220
 221 Single line comments currently look the same as JavaScript comments,
 222 aka "//" and must be placed on their own line:
 223
 224     // just some paragraphs
 225     p foo
 226     p bar
 227
 228 would output
 229
 230     <!-- just some paragraphs -->
 231     <p>foo</p>
 232     <p>bar</p>
 233
 234 Jade also supports unbuffered comments, by simply adding a hyphen:
 235
 236     //- will not output within markup
 237     p foo
 238     p bar
 239
 240 outputting
 241
 242     <p>foo</p>
 243     <p>bar</p>
 244
 245 ### Block Comments
 246
 247  A block comment is legal as well:
 248
 249       body
 250         //
 251           #content
 252             h1 Example
 253
 254 outputting
 255
 256     <body>
 257       <!--
 258       <div id="content">
 259         <h1>Example</h1>
 260       </div>
 261       -->
 262     </body>
 263
 264 Jade supports conditional-comments as well, for example:
 265
 266     body
 267       //if IE
 268         a(href='http://www.mozilla.com/en-US/firefox/') Get Firefox
 269
 270 outputs:
 271
 272     <body>
 273       <!--[if IE]>
 274         <a href="http://www.mozilla.com/en-US/firefox/">Get Firefox</a>
 275       <![endif]-->
 276     </body>
 277
 278
 279 ### Nesting
 280
 281  Jade supports nesting to define the tags in a natural way:
 282
 283     ul
 284       li.first
 285         a(href='#') foo
 286       li
 287         a(href='#') bar
 288       li.last
 289         a(href='#') baz
 290
 291 ### Block Expansion
 292
 293  Block expansion allows you to create terse single-line nested tags,
 294  the following example is equivalent to the nesting example above.
 295
 296       ul
 297         li.first: a(href='#') foo
 298         li: a(href='#') bar
 299         li.last: a(href='#') baz
 300
 301
 302 ### Attributes
 303
 304 Jade currently supports '(' and ')' as attribute delimiters.
 305
 306     a(href='/login', title='View login page') Login
 307
 308 Boolean attributes are also supported:
 309
 310     input(type="checkbox", checked)
 311
 312 Boolean attributes with code will only output the attribute when `true`:
 313
 314     input(type="checkbox", checked= someValue)
 315
 316 Multiple lines work too:
 317
 318     input(type='checkbox',
 319       name='agreement',
 320       checked)
 321
 322 Multiple lines without the comma work fine:
 323
 324     input(type='checkbox'
 325       name='agreement'
 326       checked)
 327
 328 Funky whitespace? fine:
 329
 330
 331     input(
 332       type='checkbox'
 333       name='agreement'
 334       checked)
 335
 336 Colons work:
 337
 338     rss(xmlns:atom="atom")
 339
 340 Suppose we have the `user` local `{ id: 12, name: 'tobi' }`
 341 and we wish to create an anchor tag with `href` pointing to "/user/12"
 342 we could use regular javascript concatenation:
 343
 344     a(href='/user/' + user.id)= user.name
 345
 346 or we could use jade's interpolation:
 347
 348    a(href='/user/#{user.id}')= user.name
 349
 350 The `class` attribute is special-cased when an array is given,
 351 allowing you to pass an array such as `bodyClasses = ['user', 'authenticated']` directly:
 352
 353     body(class=bodyClasses)
 354
 355 ### Doctypes
 356
 357 To add a doctype simply use `!!!`, or `doctype` followed by an optional value:
 358
 359     !!!
 360
 361 Will output the _transitional_ doctype, however:
 362
 363     !!! 5
 364
 365 or
 366
 367     !!! html
 368
 369 or
 370
 371     doctype html
 372
 373 doctypes are case-insensitive, so the following are equivalent:
 374
 375     doctype Basic
 376     doctype basic
 377
 378 Will output the _html 5_ doctype. Below are the doctypes
 379 defined by default, which can easily be extended:
 380
 381 ```javascript
 382     var doctypes = exports.doctypes = {
 383             '5': '<!DOCTYPE html>',
 384             'xml': '<?xml version="1.0" encoding="utf-8" ?>',
 385             'default': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
 386             'transitional': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
 387             'strict': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
 388             'frameset': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
 389             '1.1': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
 390             'basic': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">',
 391             'mobile': '<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">'
 392         };
 393 ```
 394
 395 To alter the default simply change:
 396
 397 ```javascript
 398     jade.doctypes.default = 'whatever you want';
 399 ```
 400
 401 ## Filters
 402
 403 Filters are prefixed with `:`, for example `:markdown` and
 404 pass the following block of text to an arbitrary function for processing. View the _features_
 405 at the top of this document for available filters.
 406
 407     body
 408       :markdown
 409         Woah! jade _and_ markdown, very **cool**
 410         we can even link to [stuff](http://google.com)
 411
 412 Renders:
 413
 414        <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>
 415
 416 Filters may also manipulate the parse tree. For example perhaps I want to
 417 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.
 418
 419     body
 420       conditionals:
 421         if role == 'admin'
 422           p You are amazing
 423         else
 424           p Not so amazing
 425
 426 Not that we no longer prefix with "-" for these code blocks. Examples of
 427 how to manipulate the parse tree can be found at _./examples/conditionals.js_ and _./examples/model.js_, basically we subclass and re-implement visitor methods as needed. 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.
 428
 429 ## Code
 430
 431 Jade currently supports three classifications of executable code. The first
 432 is prefixed by `-`, and is not buffered:
 433
 434     - var foo = 'bar';
 435
 436 This can be used for conditionals, or iteration:
 437
 438     - for (var key in obj)
 439       p= obj[key]
 440
 441 Due to Jade's buffering techniques the following is valid as well:
 442
 443     - if (foo)
 444       ul
 445         li yay
 446         li foo
 447         li worked
 448     - else
 449       p oh no! didnt work
 450
 451 Hell, even verbose iteration:
 452
 453     - if (items.length)
 454       ul
 455         - items.forEach(function(item){
 456           li= item
 457         - })
 458
 459 Anything you want!
 460
 461 Next up we have _escaped_ buffered code, which is used to
 462 buffer a return value, which is prefixed by `=`:
 463
 464     - var foo = 'bar'
 465     = foo
 466     h1= foo
 467
 468 Which outputs `bar<h1>bar</h1>`. Code buffered by `=` is escaped
 469 by default for security, however to output unescaped return values
 470 you may use `!=`:
 471
 472     p!= aVarContainingMoreHTML
 473
 474 The on exception made in terms of allowing "vanilla" JavaScript, is
 475 the `- each` token. This takes the form of:
 476
 477     - each VAL[, KEY] in OBJ
 478
 479 An example iterating over an array:
 480
 481     - var items = ["one", "two", "three"]
 482     - each item in items
 483       li= item
 484
 485 outputs:
 486
 487     <li>one</li>
 488     <li>two</li>
 489     <li>three</li>
 490
 491 iterating an object's keys and values:
 492
 493     - var obj = { foo: 'bar' }
 494     - each val, key in obj
 495       li #{key}: #{val}
 496
 497 would output `<li>foo: bar</li>`
 498
 499 You can also nest these!
 500
 501     - each user in users
 502       - each role in user.roles
 503         li= role
 504
 505 When a property is undefined, Jade will output an empty string. For example:
 506
 507     textarea= user.signature
 508
 509 when undefined would normally output "undefined" in your html, however recent
 510 versions of Jade will simply render:
 511
 512     <textarea></textarea>
 513
 514 ## Includes
 515
 516  Includes allow you to statically include chunks of Jade
 517  which lives in a separate file. The classical example is
 518  including a header and footer. Suppose we have the following
 519  directory structure:
 520
 521      ./layout.jade
 522      ./includes/
 523        ./head.jade
 524        ./tail.jade
 525
 526 and the following _layout.jade_:
 527
 528       html
 529         include includes/head
 530         body
 531           h1 My Site
 532           p Welcome to my super amazing site.
 533           include includes/foot
 534
 535 both includes _includes/head_ and _includes/foot_ are
 536 read relative to the `filename` option given to _layout.jade_,
 537 which should be an absolute path to this file, however Express
 538 and the `renderFile()` method do this for you. Include then parses
 539 these files, and injects the AST produced to render what you would expect:
 540
 541 ```html
 542 <html>
 543   <head>
 544     <title>My Site</title>
 545     <script src="/javascripts/jquery.js">
 546     </script><script src="/javascripts/app.js"></script>
 547   </head>
 548   <body>
 549     <h1>My Site</h1>
 550     <p>Welcome to my super lame site.</p>
 551     <div id="footer">
 552       <p>Copyright>(c) foobar</p>
 553     </div>
 554   </body>
 555 </html>
 556 ```
 557
 558 ## Mixins
 559
 560  Mixins are converted to regular JavaScript functions in
 561  the compiled template that Jade constructs. Mixins may
 562  take arguments, though not required:
 563
 564       mixin list
 565         ul
 566           li foo
 567           li bar
 568           li baz
 569
 570   Utilizing a mixin without args looks similar, just without a block:
 571
 572       h2 Groceries
 573       mixin list
 574
 575   Mixins may take one or more arguments as well, the arguments
 576   are regular javascripts expressions, so for example the following:
 577
 578       mixin pets(pets)
 579         ul.pets
 580           - each pet in pets
 581             li= pet
 582
 583       mixin profile(user)
 584         .user
 585           h2= user.name
 586           mixin pets(user.pets)
 587
 588    Would yield something similar to the following html:
 589
 590 ```html
 591 <div class="user">
 592   <h2>tj</h2>
 593   <ul class="pets">
 594     <li>tobi</li>
 595     <li>loki</li>
 596     <li>jane</li>
 597     <li>manny</li>
 598   </ul>
 599 </div>
 600 ```
 601
 602 ## bin/jade
 603
 604 Output html to _stdout_:
 605
 606     jade < my.jade > my.html
 607
 608 Generate _examples/*.html_:
 609
 610     jade examples/*.jade
 611
 612 Pass options:
 613
 614     jade examples/layout.jade --options '{ locals: { title: "foo" }}'
 615
 616 Usage info:
 617
 618     Usage: jade [options]
 619                 [path ...]
 620                 < in.jade > out.jade
 621     Options:
 622       -o, --options <str>  JavaScript options object passed
 623       -h, --help           Output help information
 624       -w, --watch          Watch file(s) or folder(s) for changes and re-compile
 625       -v, --version        Output jade version
 626       --out <dir>          Output the compiled html to <dir>
 627
 628 ## License
 629
 630 (The MIT License)
 631
 632 Copyright (c) 2009-2010 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
 633
 634 Permission is hereby granted, free of charge, to any person obtaining
 635 a copy of this software and associated documentation files (the
 636 'Software'), to deal in the Software without restriction, including
 637 without limitation the rights to use, copy, modify, merge, publish,
 638 distribute, sublicense, and/or sell copies of the Software, and to
 639 permit persons to whom the Software is furnished to do so, subject to
 640 the following conditions:
 641
 642 The above copyright notice and this permission notice shall be
 643 included in all copies or substantial portions of the Software.
 644
 645 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 646 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 647 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 648 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 649 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 650 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 651 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.