Getting Started

Installation

Via NPM:

$ npm install swig --save

Basic Usage

Swig has multiple ways to compile and render templates. Check the API documentation for more detailed information and usage.

var swig = require('swig');

// Compile a file and store it, rendering it later
var tpl = swig.compileFile('/path/to/template.html');
console.log(tpl({ article: { title: 'Swig is fun!' }}));

// Immediately render a Swig template from a string
console.log(swig.render('{% if foo %}Hooray!{% endif %}', { locals: { foo: true }}));

Variables

Variables that are passed to templates can be output using double-curly-brackets: . All variable output is automatically autoescaped, with the exception of function output.

Notation

Accessing properties of objects can be done using either dot-notation or bracket-notation. The following examples are equivalent:

{{ foo.bar }}
// is equivalent to
{{ foo['bar'] }}

However, notation style follows the same rules as JavaScript. If a key includes non-alpha-numeric characters, it must be accessed using bracket-notation, not dot-notation.

Bad!

{{ foo.chicken-tacos }}

The above would be the same as attempting to subract tacos from foo.chicken: {{ foo.chicken - tacos }}

Good!

{{ foo['chicken-tacos'] }}

Undefined vs Falsy Values

If a variable is not defined, don't worry, your template won't explode. Instead, an empty-string will be output in its place. However, falsy values like null, false, 0 will be rendered as they are.

Filters

Variables can be modified using using special, chainable control structures called Filters:

{{ name|title }} was born on {{ birthday|date('F jS, Y') }}
// => Jane was born on July 6th, 1985

Functions

Variables can also be JavaScript functions. It is important to note that, regardless of your autoescape setting, functions will not be auto-escaped.

var locals = { mystuff: function mystuff() { return 'Things!'; } };
swig.render('{{ mystuff() }}', { locals: locals });
// => <p>Things!</p>

If you want to enforce escaping output on functions, just pipe them to the escape filter.

{{ mystuff()|escape }}
// => &lt;p&gt;Things&lt;/p&gt;

Logic Tags

Swig includes some basic operational blocks, called Tags, for helping you control output on a larger scale than variables. Tags are written using curly-percent syntax: .

{% if foo %}bar{% endif %}

// Create a list of people, only if there are items in the people array
{% for person in people %}
  {% if loop.first %}{% endif %}
  {{ person.name }}
  {% if loop.last %}{% endif %}
{% endfor %}

end tags may also have any set of extra context within them, and will just be ignore. This is useful for scoping and understanding which block you are closing and where.

{% block tacos %}
  //...
{% endblock tacos %}
{% block burritos %}
  {% if foo %}
    // ...
  {% endif the above will render if foo == true %}
{% endblock burritos %}

View the Tags documentation for a full list of tags and usage instructions.

Comments

Comment tags are simply ignored by the parser. They will removed before your templates are rendered so that no one can see them unless they have access to your source code. Comments are written using the curly-hash syntax:

{#
This is a comment.
It will be fully stripped and ignored during parsing.
#}

Whitespace Control

Any whitespace in your templates is left in your final output templates. However, you can control the whitespace around logic tags by using whitespace controls.

To remove whitespace, simply put a dash (-) at the beginning or end of your tag to remove the preceding or following whitespace, respectively.

// seq = [1, 2, 3, 4, 5]
{% for item in seq -%}{{ item }}
{%- endfor %}
// => 12345

Note: there must not be any space between the tag open/close mark and the dash.

Template Inheritance

Swig uses extends & block for template inheritance.

layout.html

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>{% block title %}My Site{% endblock %}</title>

  {% block head %}
  <link rel="stylesheet" href="main.css">
  {% endblock %}
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

index.html

{% extends 'layout.html' %}

{% block title %}My Page{% endblock %}

{% block head %}
  {% parent %}
  <link rel="stylesheet" href="custom.css">
{% endblock %}

{% block content %}
<p>This is just an awesome page.</p>
{% endblock %}

Using Swig with Express.js

Swig is easily compatible with Express, the simple web application framework for node. The following is a basic example of integrating Swig with Express:

var app = require('express')(),
  swig = require('swig'),
  people;

// This is where all the magic happens!
app.engine('html', swig.renderFile);

app.set('view engine', 'html');
app.set('views', __dirname + '/views');

// Swig will cache templates for you, but you can disable
// that and use Express's caching instead, if you like:
app.set('view cache', false);
// To disable Swig's cache, do the following:
swig.setDefaults({ cache: false });
// NOTE: You should always cache templates in a production environment.
// Don't leave both of these to `false` in production!

app.get('/', function (req, res) {
  res.render('index', { /* template locals context */ });
});

app.listen(1337);
console.log('Application Started on http://localhost:1337/');