HTML Composition

Interpol is an HTML Composition Language. That means it's kind of like a templating language, but capable of heavy lifting. It features:

What can you do with it? Stuff like this:

let label = '%0 is a friend of %1'

def renderPeople(people)
  for person in people, friend in person.friends
    [,] | label

def renderPeople(people) when not people
  <b> 'There are no people to render' </b>

# call it

renderPeople is a partial. Its first form renders a list of interpolated strings resulting from a set of nested loops. The second form is a guarded version that catches the case when there is no people value or it is empty. How easy is that to do with your current template system? I suspect pretty difficult. Maybe not possible at all.

More About Interpolation

You might ask why the interpolation was so involved. After all, in other systems you could just embed the values directly into the resulting content. You can do something like that in Interpol as well. It would look like this: 'is a friend of'

But that approach falls down once you start localizing your application (and you probably will). Interpol was designed with localization in mind. In a real Interpol application, you'd probably define such a label in a single module of localized strings and then pull them into your template with an import statement.

You could have also performed the interpolation using named indexes rather than positional ones:

let label = '%pname is a friend of %fname'
# ... and then inside the for loop ...
[pname =, fname =] | label

Interpol and node.js

To use Interpol directly from node.js applications, npm install it like so:

npm install interpol --save

You can then include it in your Node code like so:

var interpol = require('interpol');

Using the Library

To compile a raw template into a closure, invoke interpol(String) as a function. Provide to it a string containing your template:

var compiledTemplate = interpol(someTemplateString);

This will generate a closure that takes up to two parameters, both of which are optional. The first is the data that your template renders. The second is an options object used to override the content writer interface. By default, the library writes to a JavaScript string.

    list: [
      { type: 'task', id: 1, name: 'This is my first task' },
      { type: 'story', id: 2, name: 'This is my first story' }

Express / hapi Integration

For Express or hapi View Rendering, you can install the interpol-views package with NPM:

npm install interpol-views --save

You can then follow the instructions available at the interpol-views GitHub page.

Interpol and the Browser

To add Interpol as a Bower dependency to your project, do the following:

bower install interpol --save

Inclusion in a Web Page

To include Interpol templates in the browser, they must be loaded from pre-compiled JavaScript bundles. These bundles will automatically register with Interpol when loaded, so all you have to do is load them in the right order, and then invoke them somehow:

<script src="build/interpol.min.js"
<script src="your_bundle.js"
  var your_bundle = interpol.your_bundle;
  var res = your_bundle.yourTemplate({ 
    greeting: 'hello'

Note: The Interpol command-line interface generates pre-compiled bundles. You can install this globally using npm -g install and can then invoke the tools at your terminal by typing interpol.


For source code and releases, see the Interpol GitHub Page.

For news and updates, see the Interpol Blog.

For Sublime Text support, install the Interpol package using the Package Control package manager.

For more information about the Interpol Language and API, please see the Interpol Guide (a work in progress).

For a brief introduction to Interpol and its motivations, see this Introductory Presentation

To play around with Interpol, go to the JSFiddle Example