${} Template Tag
Categories: Template Tags
${fieldNameOrExpression}
Plugin: jQuery.tmpl
Description: Used for insertion of data values in the rendered template. Evaluates the specified field (property) on the current data item, or the specified JavaScript function or expression.
-
${fieldNameOrExpression}
version added: 1.0fieldNameOrExpression The name of a field on the current data item, or a JavaScript function or expression to be evaluated.
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.
Note:
This feature and its documentation are in beta and subject to change before final release.-
Using
${}
to render values of data item fields.HTML:
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> <li><b>${Name}</b> was released in ${ReleaseYear}.</li> </tmpl> <ul id="movieList"></ul>
Code:
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 */ $( "#movieTemplate" ).tmpl( movies ) .appendTo( "#movieList" );
-
Using
${}
to evaluate an expression or call a function.HTML:
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> <tr> <td>${Name}</td> <td>${Languages.length}</td> <td>${$item.getLanguages(" - ")}</td> </tr> </tmpl> <table><tbody><tr><th>Title</th><th>Versions</th><th>Languages</th></tr></tbody> <tbody id="movieList"></tbody></table>
CSS:
table { border-collapse:collapse; width:400px; background-color:#f8f8f8; margin:10px; } table td { border:1px solid blue; padding:3px; } table th { font-weight:bold; border:2px solid blue; padding:1px; } table tbody { border:2px solid blue; }
Code:
var movies = [ { Name: "Meet Joe Black", Languages: ["English", "French"] }, { Name: "The Mighty", Languages: ["English"] }, { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] } ]; /* Render the template with the movies data */ $( "#movieTemplate" ).tmpl( movies, { getLanguages: function( separator ) { return this.data.Languages.join( separator ); } }).appendTo( "#movieList" );