Note: For information about how to render templates, see .tmpl() and jQuery.tmpl().

Template Tags

Template tags such as the ${} tag can be used within jQuery templates in addition to text and HTML markup to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc.

Other available tags include: {{each}}, {{if}}, {{else}}, {{html}}, {{tmpl}} and {{wrap}}.
Note: User-defined template tags can also be specified, by extending the jQuery.tmpl.tag map.

Using the ${} Template Tag

The following example shows how to use ${} to insert the values of the data item fields: Name and ReleaseYear.

<script id="movieTemplate" type="text/x-jquery-tmpl">
    <li><b>${Name}</b> was released in ${ReleaseYear}.</li>
</script>

<script type="text/javascript">
    var movies = [
        { Name: "The Red Violin", ReleaseYear: "1998" },
        { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
        { Name: "The Inheritance", ReleaseYear: "1976" }
    ];

    // Render the template with the movies data and insert
    // the rendered HTML under the "movieList" element
    $( "#movieTemplate" ).tmpl( movies )
        .appendTo( "#movieList" );
</script>

<ul id="movieList"></ul>

The ${field} syntax is a shortened form of the alternative syntax: {{= field}}. The following is equivalent to the template used in the example above:

<li><b>{{= Name}}</b> was released in {{= ReleaseYear}}.</li>

Evaluating Expressions and Functions

In the following example ${expression} is used to evaluate a simple expression:

Template:

<tr><td>${Languages.length}</td></tr>

Data:

var movies = [
    { Name: "Meet Joe Black", Languages: ["English", "French"] },
    { Name: "The Mighty", Languages: ["English"] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }

For more complex expressions it is preferable to place the expression within a function, then use ${myFunction(a,b)} to call the function, as in:

Template:

<tr><td>${getLanguages(Languages, " - ")}</td></tr>

Code:

function getLanguages( data, separator ) {
    return data.join( separator );
}

The above example requires the function getLanguages to be available in global scope. An alternative approach which does not require a global variable is to add the function to the template item, by passing it in with the options parameter of .tmpl():

Template:

<tr><td>${$item.getLanguages(" - ")}</td></tr>

Code:

// Render the template with the movies data
$( "#movieTemplate" ).tmpl( movies, { 
    getLanguages: function( separator ) {
        return this.data.Languages.join( separator );
    }
}).appendTo( "#movieList" );

Note the use of the $item template variable, above (see the next section), which corresponds to the template item. In the call to $item.getLanguages(), the this pointer within the function is therefore the template item, and provides access to this.data etc.

The $item and $data Template Variables

The following variables are exposed to expression evaluation within templates:

• $: The jQuery object.
• $item: The current template item - which allows access to $item.data, $item.parent, etc. as well as any user-defined values or methods passed in with the options map.
• $data: The current data item (equivalent to $item.data).
• Note: A template tag with content such as {{each}}...{{/each}} may expose additional variables to template evaluation within the content. In the case of {{each}}, for example, the additional template variables $value and $index are provided within the content of the {{each}} tag.

HTML encoding

The values rendered by ${} are evaluated as strings, and are HTML encoded. Any embedded markup will therefore be encoded. To insert the unencoded markup in the rendered template, use instead the {{html}} template tag.