Jade for Meteor with support for anonymous Meteor helper and event templates using inline CoffeeScript or JavaScript

This Meteor package provides some support for the Jade template engine as a Spacebars alternative with inline JavaScript and CoffeeScript support.

Example code

With this version of meteor-jade you can cut down a lot of code. Here is how you can write the whole simple-todos app (except the unmodified css) in less than 100 lines of code, while making the app easier to maintain:

simple-todos.coffee.jade:

head
  title Todo List

body
  .container
    header
      h1 Todo List (#{Tasks.find({checked: $ne: true}).count()})
      label.hide-completed(mt-change="Session.set 'hideCompleted', event.target.checked")
        input(type="checkbox" checked="#{Session.get 'hideCompleted'}")
        | Hide Completed Tasks #{testhelper}

      +loginButtons
      if currentUser
        form.new-task
          input(type="text" name="text" placeholder="Type to add new tasks!")
    ul
      each shownTasks()
        +task

task.tpl.coffee.jade:

li(class="{{#if checked}}checked{{/if}} {{#if private}}private{{/if}}")
    button.delete(mt-click="Meteor.call 'deleteTask', @_id") ×
    input(type="checkbox" checked=checked
        mt-click="Meteor.call 'setChecked', @_id, !@checked")
    if this.owner==Meteor.userId()
      button(mt-click="Meteor.call 'setPrivate', @_id, !@private")
        if private
          | Private
        else
          | Public
    span.text <strong>#{username}</strong> - #{text}

simple-todos.coffee:

Tasks = new (Mongo.Collection)('tasks')
@shownTasks=->
  if Session.get('hideCompleted')
    # If hide completed is checked, filter tasks
    Tasks.find { checked: $ne: true }, sort: createdAt: -1
  else
    # Otherwise, return all of the tasks
    Tasks.find {}, sort: createdAt: -1

if Meteor.isServer
  # This code only runs on the server
  # Only publish tasks that are public or belong to the current user
  Meteor.publish 'tasks', ->
    Tasks.find $or: [
      { private: $ne: true }
      { owner: @userId }
    ]
if Meteor.isClient
  # This code only runs on the client
  Meteor.subscribe 'tasks'
  Template.body.events
    'submit .new-task': (event) ->
      # Prevent default browser form submit
      event.preventDefault()
      # Get value from form element
      text = event.target.text.value
      # Insert a task into the collection
      Meteor.call 'addTask', text
      # Clear form
      event.target.text.value = ''
  Accounts.ui.config passwordSignupFields: 'USERNAME_ONLY'
Meteor.methods
  addTask: (text) ->
    # Make sure the user is logged in before inserting a task
    if !Meteor.userId()
      throw new (Meteor.Error)('not-authorized')
    Tasks.insert
      text: text
      createdAt: new Date
      owner: Meteor.userId()
      username: Meteor.user().username
  deleteTask: (taskId) ->
    task = Tasks.findOne(taskId)
    if task.private and task.owner != Meteor.userId()
      # If the task is private, make sure only the owner can delete it
      throw new (Meteor.Error)('not-authorized')
    Tasks.remove taskId
  setChecked: (taskId, setChecked) ->
    task = Tasks.findOne(taskId)
    if task.private and task.owner != Meteor.userId()
      # If the task is private, make sure only the owner can check it off
      throw new (Meteor.Error)('not-authorized')
    Tasks.update taskId, $set: checked: setChecked
  setPrivate: (taskId, setToPrivate) ->
    task = Tasks.findOne(taskId)
    # Make sure only the task owner can make a task private
    if task.owner != Meteor.userId()
      throw new (Meteor.Error)('not-authorized')
    Tasks.update taskId, $set: private: setToPrivate

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
• Examples
• Usage
  • Templates
  • HTML Tag attributes
  • Components
• Additional features
  • else if
  • Unwrapped templates
  • Anonymous helper
• Unsupported Jade Features
• Contributing
  • Implementation
  • License
  • Tests
• Known bugs
  • Using Jade in a package

Installation

Meteor-jade is installable from atmosphere, the meteor package system:

$ meteor add mquandalle:jade

Examples

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 template

There 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 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.jade

Like 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= name

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

Instead of:

if user.isAdmin
  h1 Hello admin
else
  if user.isConnected
    h1 Hello user
  else
    h1 Hello visitor

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

You can also use the .coffee.jade file extension for inline CoffeeScript, and the program accepts both .coffee.tpl.jade and .tpl.coffee.jade as Jade templates with inline CoffeeScript support.

Anonymous helpers

There is experimental support for helper functions inside the templates:

if player.score > 10
  p Well done, you have #{player.score} points!

It can be useful for conditions (if, else if and unless) and inside attributes. Anonymous helpers can't call other template helper functions though. If you want to use a helper function in multiple anonymous helpers, you have to declare it as a global function.

Anonymous events

There is experimental support for anonymous event functions inside the templates as well:

    button.delete(mt-click="Meteor.call 'deleteTask', @_id") ×

It uses the event after mt-, and uses JavaScript or CoffeeScript depending on the extension of the file. The event function can use the current object and also can access current DOM event with the event variable.

Unsupported Features

Currently the following Jade features are not supported by meteor-jade-coffee.

• 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/*

Known bugs

This is an experimental version so there can be many unknown bugs, but the biggest problem that I know of is that the program uses a heuristic to see if the code is inline anonymous helper (that can't call other helper functions) or if it is a named Meteor helper function.

Releasing

meteor publish

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",
  "xiphy:jade-coffee@0.1.6"
], "server");