Template

Ask a question

Summary

Provides basic HTML templating functionality.

Soy preferred

Usage of Template is not encouraged if a Soy template is available and/or you can write in Soy instead. Template will be phased out in future.

Status

API status: deprecated
Web resource key: com.atlassian.auiplugin:template
AMD Module key: N/A
Experimental API: 3
General API: 3.1

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:

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:

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:

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:

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:

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

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

And this is the code to put it all together:

Here is the result: