Documentation

Template

Summary

Provides basic HTML templating functionality.

Status

Code

Usage guide

• Provides the ability to populate a simple string template with data values.
• Template can be provided as a string literal or retrieved from a specific kind of markup used for templates.
• Data values are provided as a JavaScript object.
• By default, data values are automatically HTML-encoded before insertion into the template.

AUI Template should be used for the following scenarios:

• When you need to use a custom snippet of HTML, populated with data provided by the user or in a JSON response.

Do NOT use Template for these situations:

• If you want complicated logic in your template language. These templates are designed to be brain-dead simple.

Simple example

At its simplest, you can use AJS.template completely from JavaScript:

<script type="text/x-template" title="markup-template">
    Hello, {name}. Welcome to {application}.<br>
</script>

In this example, the '{location}' variable is replaced with the value of the 'location' key in the data object. On the last line, the output of the template, "Hello, world!", is appended to the element with an ID of "result".

Note that AJS.template.fill() (and its non-escaping counterpart fillHtml()) returns a template object rather than the string value of the populated template, so you will need to write code like the following if you are passing the populated template to something that expects a string:

alert(template.fill(data).toString()); // note - toString() is required because fill() returns template object

Markup examples

It is often useful to put templates in HTML for later retrieval from JavaScript. You can do this with AJS.template by putting a <script type="text/x-template"> element in your markup, with a title attribute to specify the unique name of your template:

var template = AJS.template("Hello, {location}!");
var data = { location: "world" };
AJS.$("#result").append(template.fill(data));

In this example, the template's name is "markup-template" and its body is the content of the script element.

Here's how you might load and populate this template multiple times in JavaScript:

var data = [
    { name: "John", application: "Atlassian JIRA" },
    { name: "Mary", application: "Atlassian Confluence" }
];
for (var i=0; i<data.length; i++) &#123;
    AJS.&#36;("#result").append(AJS.template.load("markup-template").fill(data[i]));
&#125;

Complicated example

First, we define a bunch of templates in the markup, using <script type="text/x-template"> elements and using the title attribute to give a unique name for each template:

<script type="text/x-template" title="test-main">
    <p>Demonstration of the templating mechanism.</p>
    <p{class}>Hello, {title}{name()}</p>
    {list}
</script>
<script type="text/x-template" title="test-class"> class="marked"</script>
<script type="text/x-template" title="test-fulllist">
    <ul>{list}</ul>
</script>
<script type="text/x-template" title="test-emptylist">
    <p>List is empty</p>
</script>
<script type="text/x-template" title="test-list">
    <li><a href="{url}">{name}</a></li>
</script>

This is a JSON data object returned from the server that we will transform and use to populate the template:

var json = {
    name: function () {return "Abraham Gopnik";},
    list: [{
            url: "http://apple.com",
            name: "Apple"
        }, {
            url: "http://google.com",
            name: "Google"
        }],
    marked: true
};

Then, here's an example of some template manipulation logic in JavaScript:

function transform(json) {
    if (json.marked) {
        json["class:html"] = AJS.template.load("test-class");
    }
    var list = "";
    for (var i = 0, ii = json.list && json.list.length; i < ii; i++) {
        list += AJS.template.load("test-list").fill(json.list[i]);
    }
    json["list:html"] = ii ? AJS.template.load("test-fulllist").fillHtml({list: list}) : AJS.template.load("test-emptylist");
    delete json.list;
    return json;
}

And this is the code to put it all together:

var r = AJS.template.load("test-main").fill(transform(json));
// we could fill title separately
r.fill({"title:html": "<strong>Mr.</strong> "});
AJS.$("#result").html(r);

Here is the result:

<p>Demonstration of the templating mechanism.</p>
<p class="marked">Hello, <strong>Mr.</strong> Abraham Gopnik</p>
<ul>
    <li><a href="http://apple.com">Apple</a></li>
    <li><a href="http://google.com">Google</a></li>
</ul>