Laurens Meurs edited this page Jul 19, 2018 · 22 revisions

twig.js

Build Status

About

Twig.js is a pure JavaScript implementation of the Twig PHP templating language (http://twig.sensiolabs.org/)

The goal is to provide a library that is compatible with both browsers and server side containers such as node.js.

Twig.js is currently a work in progress and supports a limited subset of the Twig templating language (with more coming).

NEWS

  • 6/10/2016 - Twig is now available as a template engine in Keystone.js

Download

You can get Twig.js by any of the following methods:

  1. Clone the repository

    git clone git://github.com/justjohn/twig.js.git

  2. Download an archive of the latest as a zip or tgz

The files twig.js and twig.min.js may not be up-to-date (they will be rebuilt when releasing a new version). Run make (or make -B to force building) to create these files.

Implementation Details

See the implementation details wiki page for a list of supported filters/functions/tags/tests.

Node Usage

Twig.js is available as a Node package which you can install from npm

npm install twig

Usage without Express

If you don't want to use Express, you can render a template with the following method:

import Twig from 'twig';
Twig.renderFile('./path/to/someFile.twig', {foo:'bar'}, (err, html) => {
  html; // compiled string
});

Twig.js is compatible with Express 2 and 3 and can be setup with the following code:

app.js

Express 3

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

app.configure(function(){
    app.set('views', __dirname + '/views');
    app.set('view engine', 'twig');

    // This section is optional and can be used to configure twig.
    app.set('twig options', { 
        strict_variables: false
    });
});

app.get('/', function(req, res){
    res.render('index', {
        message : "Hello World"
    });
});

app.listen(9999);

views/index.twig

Message of the moment: <b>{{ message }}</b>

Using a custom file extension

You can use a custom file extension by registering twig as the view engine for the extension you want. For example, to use the html extension, you would use:

twig = require('twig');

// ... in app.configure
app.set('view engine', 'html');
app.engine('html', twig.__express);

See the Express 2 page for compatibility with Express 2.

Browser Usage

From the browser, Twig.js can be used with inline templates or templates loaded from AJAX.

Inline Templates

var template = Twig.twig({
    id: "list", // id is optional, but useful for referencing the template later
    data: "{% for value in list %}{{ value }}, {% endfor %}"
});

var output = template.render({
    list: ["one", "two", "three"]
});

// output = "one, two, three, "

If an id is provided when you create a template, you can reference the template anywhere else in your application by using the ref parameter:

// Elsewhere in your application
var output = Twig.twig({ ref: "list" }).render({
    list: ["a", "b", "c"]
});

// output = "a, b, c, "

AJAX Templates

Templates can also be loaded via ajax by setting the href parameter in the twig() options.

templates/posts.twig

{% for post in posts %}
    <article>
        <header>
            <h1>{{ post.title }}</h1>
        </header>
        <p>{{ post.body }}</p>
    </article>
{% endfor %}

app.js

var template = twig({
    id: "posts",
    href: "templates/posts.twig",
    // for this example we'll block until the template is loaded
    async: false

    // The default is to load asynchronously, and call the load function 
    //   when the template is loaded.

    // load: function(template) { }
});

Once you've loaded templates, you can access them via their id and render them when you have data.

posts = { ... }; // data from somewhere like an AJAX callback

// render the template
var postsHTML = twig({ ref: "posts" }).render(posts);

// Display the rendered template
document.getElementById("posts").innerHTML = postsHTML;

Namespaces

var template = Twig.twig({
    data: 'your-template',
    namespaces: { 'my-project': 'path/to/views/folder/' }
}).render();

When referencing another template, instead of using the relative path you can use the namespaces that were previously defined.

Ex:

{# your-template.twig #}
{% extends "my-project::template.twig" %}

The "my-project::" will now point to "path/to/views/folder/".

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.