Home

Stamp

Stamp is a small library to stamp out DOM content from <template> elements. For more background on the <template> element see this HTML 5 Rocks' article. Please note that Stamp is not a data-binding library such as rivets.js, there is no binding between the data used to expand the template and the final DOM. This makes it very fast, but may not be appropriate for all cases.

Installation

To install the library by bower, run:

bower install wcstamp

Then include the file wcstamp/src/stamp.js.

Reference

Given the following template:

<template id=t>
  <p><a href-="{{ url }}">{{ foo.bar.baz }} {{ quux }}</a>!</p>
</template>

And the following data:

var data = {
  foo: { bar: { baz: "Hello"}},
  quux: "World",
  url: "http://example.com",
};

Then the following code will expand the template against the data and append it to the body:

var ctx = new Stamp.Context();
var expanded = Stamp.expand(ctx.import('t'), data);
Stamp.appendChildren(document.body, expanded);

The expansion will look like:

<p><a href="http://example.com">Hello World</a>!</p>

Format

Stamp uses the double moustache to delineate templated values. Note that the actual delimeters include the space before and after, so {{foo}} won't be recognized, but {{ foo }} will be. The value inside the double moustaches is called the path, and can either be simple, or a more complex path of "." separated elements. For example, given the data:

{
  name: "Planet Express",
  address: {
    street: "123 Main St.",
    city: "New New York",
  }
}

Paths can reference both simple and nested data:

<template>
  <p>{{ name }}</p>
  <p>{{ address.street }}</p>
  <p>{{ address.city }}</p>
</template>

Some DOM attributes can't have invalid values, so Stamp supports appending a trailing "-" to an attribute that will be removed when the template is expanded. For example:

<img src-="{{ image.url }}">

The trailing "-" on the src attribute will be removed upon template expansion.

Iteration

Stamp allows iterating over both Objects and Arrays. Stamp use a data- attribute to control iteration, of the form:

data-repeat-name[-index]="{{ path }}"

For example, given the data:

var characters = ["Amy", "Leela", "Fry", "Zoidberg", "Hermes", "Bender"];

The following template will loop over all the characters and emit a <p> element for each one. Since we are looping over an Array the index variable i is available for expansion.

<template>
  <div data-repeat-firstname="{{ characters }}">
    <p>{{ i }}. {{ firstname }}</p>
  </div>
</template>

If you want to use a different name for the index you can supply that as an optional [-name] postfix to the attribute.

<div data-repeat-firstname-index="{{ characters }}">
  <p>{{ index }}. {{ firstname }}</p>
</div>

The format for iterating over Objects is identical. The only difference in behavior is that instead of "i" for index, the state variable "key" is used.

<ul data-repeat-value="{{ some.object }}">
  <li>{{ key }}: {{ value }}</li>
</ul>

If you want to use a different name for the key you can supply that as an optional [-name] postfix to the attribute.

<ul data-repeat-value-mykey="{{ some.object }}">
  <li>{{ mykey }}: {{ value }}</li>
</ul>

Both types of loops can be nested:

  data: [
    ["a", "b", "c"],
    ["1", "2", "3"],
  ]

  <div data-repeat-row="{{ data  }}">
    <p>Row {{ i }}
      <ol data-repeat-value="{{ row }}">
        <li>{{ value }}</li>
      </ol>
    </p>
  </div>

When using loops you can use the path ^ to reference data up one level of nesting, and you can add as many ^'s as you need:

  data: [
    ["a", "b", "c"],
    ["1", "2", "3"],
  ]

  <div data-repeat-row-rownum="{{ data  }}">
    <p>
      <ol data-repeat-value="{{ row }}">
        <li>{{ value }} appears in row {{ ^.rownum }}</li>
      </ol>
    </p>
  </div>

API

Context

Stamp.Context is a utilty object to capture the document context of the script tag that instantiated the Context. Useful for getting access to assets in HTML Imports. It needs to be instantiated in the same context as the <template> elements it is going to reference. It supports only a single method:

• import(id) - Creates a copy of the template node that can be inserted into the current document.

Stamp

Stamp exposes the following functions:

• appendChildren(ele, nodes) - Append all the elements in 'nodes' as children of 'ele'.
• expand(ele, state) - Expand all the double moustaches found in the node 'ele' and all its children against the data in 'state'. When descending into nested templates, i.e. a data-repeat- template then '^' is added to the child state as a way to access the data in the parent's scope.
• expandInto(target, ele, state) - Expand the template 'ele' with 'state' and then replace all the children of 'target' with the expanded content.

See the How_to_use.html file for examples of these functions in action.