Jade for Meteor
This Meteor package provides some support for the Jade template engine as a Spacebars alternative.
Spacebars and Jade packages can coexist, Spacebars will continue to compile
files ending with .html and Jade will take care of those ending with .jade.
Table of Contents
Installation
Meteor-jade is installable from atmosphere, the meteor package system:
$ meteor add mquandalle:jadeExamples
Meteor comes with some examples such as leaderboard or todos. You'll find jade versions of those examples templates and even more in the examples directory.
Usage
Meteor-jade works somewhat like Jade, so if you never use Jade before you should take a look at the documentation.
There are some specifics rules relative to the Meteor way of handling templates. These rules are mostly the same as the Spacebars ones.
Templates
Every HTML tag must be in a template. You can define a template with the following syntax:
template(name="myTemplate")
p This paragraph is inside my templateThere are two particular templates that are automatically rendered inside the
DOM: head and body. If you want to include a template inside another,
precede its name by the + symbol:
head
title Leaderboard
body
+leaderboard
//- This is equivalent to {{> leaderboard}}Inside a text node you can use both {{spacebars}} and #{jade} expressions
but the last one is recommended:
template(name="leaderboard")
p Welcome #{player.name}If you indent after a div or similar element, you can use | symbol in order jade not
to confuse with tags:
template(name='leaderboard')
#content
| #{greeting}You can also use = as a shortcut:
template(name='leaderboard')
#content
= greetingIf you want to insert raw HTML you can use the !{jade} syntax which is
equivalent to the triple-braced {{{spacebars}}} expression.
HTML Tag attributes
In Jade you define HTML Tag attributes inside parenthesis:
input(name="myName" placeholder="name" autofocus)If you want to conditionally include a HTML Tag attribute you can use the following syntax:
input(required = isRequired)Where isRequired is a (potentially reactive) boolean defined in a template
helper. If you want to add a list of dynamic attributes use:
input($dyn = attrs)Spacebars equivalent:
<input {{attrs}}>Components
As you may already know, Meteor templates are "components" as well. To use a
template as a component, you simply have to provide a content block and
optionally a elseContent block after the inclusion:
body
+ifEven(value=2)
| Hello world
else
| Bye world
//-
This is the equivalent of:
{{#ifEven value=2}}
Hello world
{{else}}
Bye world
{{/ifEven}}
ifEven is a component defined by the user
See the complete example in ./examples/components.jadeLike with Spacebars, a component can receive both ordered and keywords arguments. Keywords arguments must be written after the ordered ones:
+myComponent(arg1 arg2 arg3 key1=val1 key2=val2)
Brackets are optional:
+myComponent arg1 arg2 arg3 key1=val1 key2=val2
For the four built-in components (if, unless, each and with) the +
is also optional:
ul
each players
if isSelected
li.selected= name
else
li= nameAdditional features
We have some additional features over Spacebars.
else if
We provide syntaxic sugar so you can write:
if user.isAdmin
h1 Hello admin
else if user.isConnected
h1 Hello user
else
h1 Hello visitorInstead of:
if user.isAdmin
h1 Hello admin
else
if user.isConnected
h1 Hello user
else
h1 Hello visitorUnder the hood, those two codes are compiled to the same abstract tree, so there are no runtime performance hit.
Unwrapped templates
Putting each template in its own separate file and naming the file after the template it contains is becoming a followed pattern among Meteor developers. See for instance this article from Josh Owens.
But as it stands today, this pattern doesn't respect the “don't repeat yourself”
(DRY) philosophy. Indeed you have to wrap your template in a
<template name="myTemplate> tag and saving it in a myTemplate.html file,
effectively writing the name of the template twice. If those two names doesn't
match Meteor will consider the name of the <template> tag and will ignore the
file name. So if you follow this pattern you have to take care of keeping the
file name and the template tag name in sync (manually).
We solve this problem using a new the .tpl.jade file extension. With it you
can only define one template per file and you don't need to wrap your template
in a tag. The template will be named after the file name. We handle special
head.tpl.jade and body.tpl.jade templates as expected.
Anonymous helper
This feature is not yet implemented. However, once implemented it could:
if player.score > 10
p Well done!It'll be useful for conditions (if, else if and unless) and inside
attributes.
See related issue
Unsupported Features
Currently the following Jade features are not supported by meteor-jade.
- Code
- Case
- Filter
Contributing
Contributions are welcome, whether it is for a bug report, a fix or a new functionnality proposition.
Implementation
This package use the Jade lexer to define the grammar, we just add a few customs rules specifics to the Meteor components model. Then we use the Jade parser which returns a syntax tree that we transform to make it compatible with the Meteor format. We finally rely on the Spacebars compiler to generate the JavaScript code sent to the client.
Everything is executed at bundle time.
License
This code is published under the MIT license.
Tests
Use the following command to run the tests:
$ meteor test-packages packages/*
Tips
If you want to buy me a beer, I proudly accept bitcoin tips: 1Jade7Fscsx2bF13iFVVFvcSUhe7eLJgSy
Known bugs
Using Jade in a package
When using Jade in a package you need to lock the version to the latest version manually. See issue #83.
api.use([
"templating",
"mquandalle:[email protected]"
], "client");