Skip to content

Latest commit

 

History

History
292 lines (185 loc) · 7.2 KB

Readme.md

File metadata and controls

292 lines (185 loc) · 7.2 KB
Raw

Jade - template engine

Jade is a high performance template engine heavily influenced by Haml and implemented with JavaScript for node.

Features

  • high performance parser
  • great readability
  • code is escaped by default for security
  • contextual error reporting at compile & run time
  • executable for compiling jade templates via the command line
  • html 5 mode (using the !!! 5 doctype)
  • optional memory caching
  • combine dynamic and static tag classes
  • supports Express JS
  • no tag prefix
  • filters
    • :sass must have sass.js installed
    • :less must have less.js installed
    • :markdown must have markdown-js installed
    • :cdata
    • :javascript

Installation

via tarball or git:

make install

via npm:

npm install jade

via kiwi:

kiwi install jade

Public API

var jade = require('jade');

// Render a string
jade.render('string of jade', { options: 'here' });

// Render a file
jade.renderFile('path/to/some.jade', { options: 'here' }, function(err, html){
    // options are optional,
    // the callback can be the second arg
});

Options

  • scope Evaluation scope (this)
  • locals Local variable object
  • filename Used in exceptions, and required by cache
  • cache Cache intermediate JavaScript in memory keyed by filename
  • debug Outputs tokens and function body generated

Syntax

Line Endings

CRLF and CR are converted to LF before parsing.

Indentation

Jade is indentation based, however currently only supports a 2 space indent. We may implement tab support in the future, until then use spaces, so make sure soft tabs are enabled in your editor.

Tags

A tag is simply a leading word:

html

for example is converted to <html></html>

tags can also have ids:

div#container

which would render <div id="container"></div>

how about some classes?

div.user-details

renders <div class="user-details"></div>

multiple classes? and an id? sure:

div#foo.bar.baz

renders <div id="foo" class="bar baz"></div>

div div div sure is annoying, how about:

#foo
.bar

which is syntactic sugar for what we have already been doing, and outputs:

`<div id="foo"></div><div class="bar"></div>`

Tag Text

Simply place some content after the tag:

p wahoo!

renders <p>wahoo!</p>.

well cool, but how about large bodies of text:

p
  | foo bar baz
  | rawr rawr
  | super cool
  | go jade go

renders <p>foo bar baz rawr.....</p>

interpolation? yup! both types of text can utilize interpolation, if we passed { locals: { name: 'tj', email: 'tj@vision-media.ca' }} to render() we can do the following:

#user #{name} &lt;#{email}&gt;

outputs <div id="user">tj &lt;tj@vision-media.ca&gt;</div>

Actually want #{} for some reason? escape it!

p \#{something}

now we have <p>#{something}</p>

Nesting

ul
  li one
  li two
  li three

Fucked up your whitespace? no worries, jade's error reporting should help you out. Jade instruments the compiled JavaScript to provide meaningful context for runtime exceptions.

ul
    li one
  li two

Error: /Users/tj/Projects/jade/examples/layout.jade:2
    1. 'ul'
    2. '    li one'

Invalid indentation, got 2 expected 1.

Note: Trailing are generated on EOS if not present.

Attributes

Jade currently supports '(' and ')' as attribute delimiters.

a(href='/login', title='View login page') Login

Alternatively we may use the colon to separate pairs:

a(href: '/login', title: 'View login page') Login

Boolean attributes are also supported:

input(type="checkbox", checked)

Boolean attributes with code will only output the attribute when true:

input(type="checkbox", checked: someValue)

Note: Leading / trailing whitespace is ignore for attr pairs.

Doctypes

To add a doctype simply use !!! followed by an optional value:

!!!

Will output the transitional doctype, however:

!!! 5

Will output html 5's doctype. Below are the doctypes defined by default, which can easily be extended: var doctypes = exports.doctypes = { '5': '', 'xml': '', 'default': '', 'transitional': '', 'strict': '', 'frameset': '', '1.1': '', 'basic': '', 'mobile': '' };

To alter the default simply change:

jade.doctypes.default = 'whatever you want';

Filters

Filters are prefixed with :, for example :markdown and pass the following block of text to an arbitrary function for processing. View the features at the top of this document for available filters.

body
  :markdown
    | Woah! jade _and_ markdown, very **cool**
    | we can even link to [stuff](http://google.com)

Renders:

   <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>

Code

Jade currently supports three classifications of executable code. The first is prefixed by -, and is not buffered:

- var foo = 'bar';

This can be used for conditionals, or iteration:

- for (var key in obj)
  p= obj[key]

Due to Jade's buffering techniques the following is valid as well:

- if (foo)
  ul
    li yay
    li foo
    li worked
- else
  p shit! didnt work

Hell, even verbose iteration:

- if (items.length)
  ul
    - items.forEach(function(item){
      li= item
    - })

Anything you want!

Next up we have escaped buffered code, which is used to buffer a return value, which is prefixed by =:

- var foo = 'bar'
= foo
h1= foo

Which outputs bar<h1>bar<h1/>. Code buffered by = is escaped by default for security, however to output unescaped return values you may use !=:

p!= aVarContainingMoreHTML

bin/jade

Output html to stdout:

jade examples/*.jade --pipe

Generate examples/*.html:

jade examples/*.jade

Pass options:

jade examples/layout.jade --options '{ locals: { title: "foo" }}'

Usage info:

�Usage: jade [options] <path ...>

�Options:
  -o, --options STR   JavaScript options object passed
  -p, --pipe          Output to stdout instead of PATH.html
  -h, --help          Output help information