getting-started.md

Getting Started #

Init Swig #

In order to start using Swig, you should initialize it. Swig can be configured using the following:

swig.init({
    allowErrors: false,
    autoescape: true,
    encoding: 'utf8',
    filters: {},
    root: '/',
    tags: {},
    extensions: {},
    tzOffset: 0
});

This step is optional, however it is recommended to at least set the root key when running Swig from node.js.

Options

allowErrors optional

Default is false. Keeping this off will render all template parsing and compiling errors straight to the template output. If true, errors will be thrown straight to the Node.js process, potentially crashing your application.

autoescape optional

Automatically escape all variable output. This is the default behavior and it is highly recommended to leave this on.

Possible Values

• true - Will escape output safe for HTML.
• false - Will not escape any output unless forced via the escape filter or autoescape tag.
• 'js' - Will escape output safe for JavaScript.

For character conversion tables, see the escape filter.

encoding optional

The character encoding for template files. Defaults to utf8.

filters optional

Use this to set any custom filters and/or override any of the built-in filters. For more information on writing your own filters, see the custom filters guide.

root optional

The directory to search for templates. If a template passed to swig.compileFile is an absolute path (starts with /), Swig will not look in the template root.

tags optional

Use this to set any custom tags and/or override any of the built-in tags. For more information on writing your own tags, see the custom tags guide.

extensions optional

Add library extensions that will be available to compiled templates. For more information, see the custom tags guide on third party extensions.

tzOffset optional

Sets a default timezone offset, in minutes from GMT. Setting this will make the date filter automatically convert dates parsed through the date filter to the appropriate timezone offset.

Parsing a Template #

You have 2 methods for creating a template object:

swig.compileFile("path/to/template/file.html");
swig.compile("Template string here", { filename: 'templateKey' });

Rendering a Template #

Both of these methods will give you a template object on which you call the render method passing it a map of context values.

var tpl = swig.compileFile("path/to/template/file.html");
var renderedHtml = tpl.render({ vars: 'to be inserted in template' });

OR

var tpl = swig.compile("Template string here");
var renderedHtml = tpl({ vars: 'to be inserted in template' });