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

This method compiles the markup in the template parameter as a named template, which can be referenced using the string specified in the name parameter.

The return value is the compiled-template function.

See also template().

Note: The named template is added to the $.template map.

• To determine if a string "someName" is the name of a named template, test whether $.template["someName"] is defined.
• To remove a previously created named template, use
  delete $.template["someName"];

Example: Create a compiled template associated with the name "summaryTemplate" and then reference it by name for rendering:

// Convert the markup string into a named template
$.template( "summaryTemplate", "<li>${Name}</li>" );

function renderList() {
    // Render the movies data using the named template: "summaryTemplate"
    $.tmpl( "summaryTemplate", movies ).appendTo( "#moviesList" );
}

Example: Use the return value rather than the name string to reference the compiled template:

// Convert the markup string into a compiled template
var myTemplate = $.template( null, "<li>${Name}</li>" ); 

function renderList() {
    // Render movies data using the compiled template: myTemplate
    $.tmpl( myTemplate, movies ).appendTo( "#moviesList" );
}

Example: Create a named template and reference it by name as a nested template:

<script id="movieTemplate" type="text/x-jquery-tmpl">
    {{tmpl "summaryTemplate"}}
    <tr><td>Director: ${Director}</td></tr>
</script>
___________

// Convert the markup string into a named template,
// referenced by the {{tmpl}} tag
$.template( "summaryTemplate", "<tr><td>${Name}</td></tr>" );

// Render the movies data, using the named template as a nested template
$( "#movieTemplate" ).tmpl( movies ).appendTo( "#movieList" );

Optimizing Template Rendering

When a template is rendered, using .tmpl() or jQuery.tmpl(), the markup is first converted into a compiled-template function. In the case of markup obtained from a string, the use of .template() as in the above examples ensures that the conversion from markup to a compiled-template function only happens once.

On the other hand, passing a markup string template directly to .tmpl() or to {{tmpl}} for rendering will not be optimal from a performance point of view, since the markup will be re-compiled every time:

var markup = "<li>${Name}</li>";

function renderList() {
  // Sub-optimal: the markup string will be
  // recompiled each time renderList is called
  $.tmpl( markup, movies ).appendTo( "#moviesList" );
}

Note: In the case of inline templates declared within a script block, caching occurs automatically, so the following example does correspond to best practice:

Example: Rendering an inline template directly without compiling as a named template.

<script id="summaryTemplate" type="text/x-jquery-tmpl">
    <li>${Name}</li>
</script>
___________

function renderList() {
  // The template will be compiled only once,
  // so this is approach can be optimal.
  $( "#summaryTemplate" ).tmpl( movies ).appendTo( "#moviesList" );
}

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

If the template parameter is the name string for a named template created using $.template( name, template ), this method returns the compiled template for the named template (equivalent to $.template[name]).

Otherwise, if the template parameter is a string containing HTML markup, then this method will return a compiled template for the markup provided.

If the template parameter is a string containing pure text (no HTML tags), then the string is treated as a selector for an inline template, whose content will be used as markup. Similarly if template is an HTML element (or jQuery object wrapping an element), then the content will be used as markup for the returned compiled template.

Example: Switch the template item to a different template, using $.template( name ), :

// Create the compiled templates
$.template( "summaryTemplate", "<tr>...</tr>" );
$.template( "detailTemplate", "<tr>...</tr>" );

// Render the summaryTemplate with the "movies" data 
$.tmpl( "summaryTemplate", movies ).appendTo( "#movieList" );

$( "tr" ).click( function () {
    // Switch the template for this template item to
    // a different named template, then update the rendered item
    var tmplItem = $.tmplItem(this);
    tmplItem.tmpl = $.template( "detailTemplate" );
    tmplItem.update();
});