The .tmpl() method is designed for chaining with .appendTo, .prependTo, .insertAfter or .insertBefore as in the following example.

Example:

$( "#myTemplate" ).tmpl( myData ).appendTo( "#target" );

If data is an array, the template is rendered once for each data item in the array. If data is an object, or if the data parameter is missing or null, a single template item is rendered.

The return value is a jQuery collection of elements made up of the rendered template items (one for each data item in the array). If the template contains only one top-level element, then there will be one element for each data item in the array.

To insert the rendered template items into the HTML DOM, the returned jQuery collection should not be inserted directly into the DOM, but should be chained with .appendTo, .prependTo, .insertAfter or .insertBefore, as in the example above:

See also jQuery.tmpl().

The following example shows how to use .tmpl() to render local data using an inline template.

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

<script id="movieTemplate" type="text/x-jquery-tmpl">
    <li><b>${Name}</b> (${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>

Using Remote Data

Typically the data is not local and is instead obtained using an Ajax request to a remote service or page, as in the following example:

$.ajax({
    dataType: "jsonp",
    url: moviesServiceUrl,
    jsonp: "$callback",
    success: showMovies
});

// Within the callback, use .tmpl() to render the data.
function showMovies( data ) {
    // Render the template with the "movies" data and insert
    // the rendered HTML under the 'movieList' element
    $( "#movieTemplate" ).tmpl( data )
        .appendTo( "#movieList" );
}

The Container Element for the Template

You can get the markup for the template from inline markup in the page, or from a string (possibly computed, or obtained remotely). For an example of how to get the markup from a string, see jQuery.tmpl().

If a template is defined inline in the page, you can use $( selector ).tmpl( data ), where selector is a selector referencing the container element that wraps the markup. The container can be any element, such as a <div> element whose style attribute includes display:none. However, this can result in invalid HTML or lead to side effects as a result of the browser parsing the markup and loading it into the DOM. Therefore, a preferred approach is to use a script tag such as <script id="myContainer" type="text/x-jquery-tmpl"> to wrap the markup. For the browser, the content will then be treated simply as text.

Caching the Template

When a template is rendered, the markup is first converted into a compiled-template function. In the case of inline markup, calling $( "#myContainer" ).tmpl( myData ) automatically causes the compiled template to be cached. (The cached template is associated with the DOM element that wraps the markup, using the jQuery .data() feature).

For convenience, you can also use $( "#myContainer" ).template( name ) so that you can reference the cached template by name. (See .template() for examples).

Template Tags, Expressions, and Template Variables

Template tags such as the ${} tag can 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. Template tags can render content based on the values of data item fields or template variables such as $item (corresponding to the template item), as well as expressions and function calls. See the documentation topics for each template tag: ${}, {{each}}, {{if}}, {{else}}, {{html}}, {{tmpl}} and {{wrap}}.

The options Parameter, and Template Items

Each template item (the result of rendering a data item with the template) is associated with a tmplItem data structure, which can be accessed using jQuery.tmplItem() and .tmplItem(), or the $item template variable. Any fields or anonomyous methods passed in with the options parameter of .tmpl() will extend the tmplItem data structure, and so be available to the template as in the following example:

Code:

// Render the template with the movies data
$( "#movieTemplate" ).tmpl( movies,
    { 
        myValue: "somevalue",
        myMethod: function() { 
            return "something";
        } 
    } 
).appendTo( "#movieList" );

Template:

<script id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li>
        Some content: ${$item.myMethod()}.<br/>
        More content: ${$item.myValue}.
    </li>
</script> 

• Netflix recently changed the API that we use in the remote service example below. We are aware that this change breaks the demo and will work on an update as soon as we can.
• A new template plugin fully supported by the jQuery Team is now being developed as part of jQuery UI. More details on the history of this decision can be found on the jQuery blog. Track progress and participate in the design on the jQuery UI Planning Wiki.