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

Template Tags

Template tags such as the {{wrap}} tag can be used within jQuery templates in addition to text and HTML markup, in order 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}} and {{tmpl}}. User-defined template tags can also be specified, by extending the jQuery.tmpl.tag map.

The {{wrap}} and {{tmpl}} Template Tags

The {{wrap}} template tag is similar to the {{tmpl}} template tag, except that it provides additional support for incorporating wrapped HTML content into the rendered output. The use of the template, data and options parameters is the same for both tags. (See {{tmpl}} for additional information and examples).

When using {{wrap}} the template parameter will usually correspond to template markup which uses the $item.html() feature to incorporate the wrapped markup. The template parameter can be any of the following:

• A string containing markup.
• An HTML element (or jQuery object that wraps an element) whose content is to be used as the template.
• A string corresponding to the name of a named template (see jQuery.template() and .template()).
• A compiled-template function (see jQuery.template() and .template()).

With {{wrap}}, the data parameter will often be unspecified, since the rendered output can be driven by the wrapped HTML rather than by data. If data is specified and 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.

Using the {{wrap}} Template Tag

The following example shows how to use {{wrap}} to render a nested template that incorporates the wrapped HTML. In this case the content of the {{wrap}} template tag is a set of div elements. The chosen template, tableWrapper, extracts each div and wraps it in a table cell.

<script id="myTmpl" type="text/x-jquery-tmpl">
    The following wraps some HTML content:
    {{wrap "#tableWrapper"}}
        <div>
            First <b>content</b>
        </div>
        <div>
            And <em>more</em> <b>content</b>...
        </div>
    {{/wrap}}
</script>

<script id="tableWrapper" type="text/x-jquery-tmpl">
    <table><tbody>
        <tr>
            {{each $item.html("div")}}
                <td>
                    {{html $value}}
                </td>
            {{/each}}
        </tr>
    </tbody></table>
</script>

The $item.html() Method

Any HTML content between the opening and closing tags of {{wrap}} is made available to the template as a $item.html( filter, textOnly ) method on the template item.

The return value of $item.html() is a filtered array of markup strings taken from the wrapped content:

• Use $item.html() without parameters to return all the top-level elements of the wrapped HTML content.
• Pass a selector string as filter parameter to return a filtered subset of the top-level elements. (The default value of filter is "*").
• If textOnly is set to true $item.html( filter, textOnly ) returns the inner text of the filtered subset of top-level elements.

The following example shows how to incorporate both HTML and text content into the rendered output.

<script id="myTmpl" type="text/x-jquery-tmpl">
    The following wraps and reorders some HTML content:
    {{wrap "#tableWrapper"}}
        <h3>One</h3>
        <div>
            First <b>content</b>
        </div>
        <h3>Two</h3>
        <div>
            And <em>more</em> <b>content</b>...
        </div>
    {{/wrap}}
</script>

<script id="tableWrapper" type="text/x-jquery-tmpl">
    <table><tbody>
        <tr>
            {{each $item.html("h3", true)}}
                <td>
                    ${$value}
                </td>
            {{/each}}
        </tr>
        <tr>
            {{each $item.html("div")}}
                <td>
                    {{html $value}}
                </td>
            {{/each}}
        </tr>
    </tbody></table>
</script>

Including Template Tags in Wrapped Content

The HTML markup between the opening and closing tags of {{wrap}} can include other template tags. The following example uses nested {{wrap}}tags to created nested tab views:

<script id="myTmpl" type="text/x-jquery-tmpl">
    {{wrap "#tabsWrap"}}
        <h3>One</h3>
        <div>
            First <b>tab</b>
        </div>
        <h3>Two</h3>
        <div>
            <b>Second</b> tab
            {{wrap "#tabsWrap"}}
                <h3>InnerOne</h3>
                <div>
                    Inner first <b>tab</b>
                </div>
                <h3>InnerTwo</h3>
                <div>
                    Inner <b>second</b> tab
                </div>
            {{/wrap}}
        </div>
    {{/wrap}}
</script>