The goal of this blog entry is to provide you with enough information to start working with jQuery Templates. jQuery Templates enable you to display and manipulate data in
the browser. For example, you can use jQuery Templates to format and display a set of database records that you have retrieved with an Ajax call. jQuery Templates supports a number of powerful features such as template tags, template composition, and wrapped templates. I’ll concentrate on
the features that I think that you will find most useful. In order to focus on
the jQuery Templates feature itself, this blog entry is server technology agnostic. All
the samples use HTML pages instead of ASP.NET pages. In a future blog entry, I’ll focus on using jQuery Templates with ASP.NET Web Forms and ASP.NET MVC (You can do some pretty powerful things when jQuery Templates are used on
the client and ASP.NET is used on
the server). Introduction to jQuery Templates
The jQuery Templates plugin was developed by
the Microsoft ASP.NET team in collaboration with
the open-source jQuery team. While working at Microsoft, I wrote
the original proposal for jQuery Templates, Dave Reed wrote
the original code, and Boris Moore wrote
the final code.
The jQuery team – especially John Resig – was very involved in each step of
the process. Both
the jQuery community and ASP.NET communities were very active in providing feedback. jQuery Templates will be included in
the jQuery core library (the jQuery.js library) when jQuery 1.5 is released. Until jQuery 1.5 is released, you can download
the jQuery Templates plugin from
the jQuery Source Code Repository or you can use jQuery Templates directly from
the ASP.NET CDN.
The documentation for jQuery Templates is already included with
the official jQuery documentation at http://api.jQuery.com.
The main entry for jQuery templates is located under
the topic plugins/templates. A Basic Sample of jQuery Templates Let’s start with a really simple sample of using jQuery Templates. We’ll use
the plugin to display a list of books stored in a JavaScript array. Here’s
the complete code: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html >
<head>
<title>Intro</title>
<link href="0_Site.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="pageContent">
<h1>ASP.NET Bookstore</h1>
<div id="bookContainer"></div>
</div>
<script id="bookTemplate" type="text/x-jQuery-tmpl">
<div>
<img src="BookPictures/${picture}" alt="" />
<h2>${title}</h2>
price: ${formatPrice(price)}
</div>
</script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
// Create an array of books
var books = [
{ title: "ASP.NET 4 Unleashed", price: 37.79, picture: "AspNet4Unleashed.jpg" },
{ title: "ASP.NET MVC Unleashed", price: 44.99, picture: "AspNetMvcUnleashed.jpg" },
{ title: "ASP.NET Kick Start", price: 4.00, picture: "AspNetKickStart.jpg" },
{ title: "ASP.NET MVC Unleashed iPhone", price: 44.99, picture: "AspNetMvcUnleashedIPhone.jpg" },
];
// Render
the books using
the template
$("#bookTemplate").tmpl(books).appendTo("#bookContainer");
function formatPrice(price) {
return "$" + price.toFixed(2);
}
</script>
</body>
</html>
When you open this page in a browser, a list of books is displayed:
There are several things going on in this page which require explanation.
First, notice that
the page uses both
the jQuery 1.4.4 and jQuery Templates libraries. Both libraries are retrieved from
the ASP.NET CDN:
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
You can use
the ASP.NET CDN for free (even for production websites). You can learn more about
the files included on
the ASP.NET CDN by visiting
the ASP.NET CDN documentation page.
Second, you should notice that
the actual template is included in a script tag with a special MIME type:
<script id="bookTemplate" type="text/x-jQuery-tmpl">
<div>
<img src="BookPictures/${picture}" alt="" />
<h2>${title}</h2>
price: ${formatPrice(price)}
</div>
</script>
This template is displayed for each of
the books rendered by
the template.
The template displays a book picture, title, and price.
Notice that
the SCRIPT tag which wraps
the template has a MIME type of text/x-jQuery-tmpl. Why is
the template wrapped in a SCRIPT tag and why
the strange MIME type?
When a browser encounters a SCRIPT tag with an unknown MIME type, it ignores
the content of
the tag. This is
the behavior that you want with a template. You don’t want a browser to attempt to parse
the contents of a template because this might cause side effects.
For example,
the template above includes an <img> tag with a src attribute that points at “BookPictures/${picture}”. You don’t want
the browser to attempt to load an image at
the URL “BookPictures/${picture}”. Instead, you want to prevent
the browser from processing
the IMG tag until
the ${picture} expression is replaced by with
the actual name of an image by
the jQuery Templates plugin.
If you are not worried about browser side-effects then you can wrap a template inside any HTML tag that you please. For example,
the following DIV tag would also work with
the jQuery Templates plugin:
<div id="bookTemplate" style="display:none">
<div>
<h2>${title}</h2>
price: ${formatPrice(price)}
</div>
</div>
Notice that
the DIV tag includes a style=”display:none” attribute to prevent
the template from being displayed until
the template is parsed by
the jQuery Templates plugin.
Third, notice that
the expression ${…} is used to display
the value of a JavaScript expression within a template. For example,
the expression ${title} is used to display
the value of
the book title property. You can use any JavaScript function that you please within
the ${…} expression. For example, in
the template above,
the book price is formatted with
the help of
the custom JavaScript formatPrice() function which is defined lower in
the page.
Fourth, and finally,
the template is rendered with
the help of
the tmpl() method.
The following statement selects
the bookTemplate and renders an array of books using
the bookTemplate.
The results are appended to a DIV element named bookContainer by using
the standard jQuery appendTo() method.
$("#bookTemplate").tmpl(books).appendTo("#bookContainer");
Using Template Tags
Within a template, you can use any of
the following template tags.
{{tmpl}} – Used for template composition. See
the section below.
{{wrap}} – Used for wrapped templates. See
the section below.
{{each}} – Used to iterate through a collection.
{{if}} – Used to conditionally display template content.
{{else}} – Used with {{if}} to conditionally display template content.
{{html}} – Used to display
the value of an HTML expression without encoding
the value. Using ${…} or {{= }} performs HTML encoding automatically.
{{= }}-- Used in exactly
the same way as ${…}.
{{! }} – Used for displaying comments.
The contents of a {{!...}} tag are ignored.
For example, imagine that you want to display a list of blog entries. Each blog entry could, possibly, have an associated list of categories.
The following page illustrates how you can use
the { if}} and {{each}} template tags to conditionally display categories for each blog entry:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>each</title>
<link href="1_Site.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="blogPostContainer"></div>
<script id="blogPostTemplate" type="text/x-jQuery-tmpl">
<h1>${postTitle}</h1>
<p>
${postEntry}
</p>
{{if categories}}
Categories: {{each categories}} <i>${$value}</i> {{/each}}
{{else}}
Uncategorized
{{/if}}
</script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
var blogPosts = [
{
postTitle: "How to fix a sink plunger in 5 minutes",
postEntry: "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.",
categories: ["HowTo", "Sinks", "Plumbing"]
},
{
postTitle: "How to remove a broken lightbulb",
postEntry: "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.",
categories: ["HowTo", "Lightbulbs", "Electricity"]
},
{
postTitle: "New associate website",
postEntry: "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna."
}
];
// Render
the blog posts
$("#blogPostTemplate").tmpl(blogPosts).appendTo("#blogPostContainer");
</script>
</body>
</html>
When this page is opened in a web browser,
the following list of blog posts and categories is displayed:
Notice that
the first and second blog entries have associated categories but
the third blog entry does not.
The third blog entry is “Uncategorized”.
The template used to render
the blog entries and categories looks like this:
<script id="blogPostTemplate" type="text/x-jQuery-tmpl">
<h1>${postTitle}</h1>
<p>
${postEntry}
</p>
{{if categories}}
Categories: {{each categories}} <i>${$value}</i> {{/each}}
{{else}}
Uncategorized
{{/if}}
</script>
Notice
the special expression $value used within
the {{each}} template tag. You can use $value to display
the value of
the current template item. In this case, $value is used to display
the value of each category in
the collection of categories.
Template Composition
When building a fancy page, you might want to build a template out of multiple templates. In other words, you might want to take advantage of template composition.
For example, imagine that you want to display a list of products. Some of
the products are being sold at their normal price and some of
the products are on sale. In that case, you might want to use two different templates for displaying a product: a productTemplate and a productOnSaleTemplate.
The following page illustrates how you can use
the {{tmpl}} tag to build a template from multiple templates:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Composition</title>
<link href="2_Site.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="pageContainer">
<h1>Products</h1>
<div id="productListContainer"></div>
<!-- Show list of products using composition -->
<script id="productListTemplate" type="text/x-jQuery-tmpl">
<div>
{{if onSale}}
{{tmpl "#productOnSaleTemplate"}}
{{else}}
{{tmpl "#productTemplate"}}
{{/if}}
</div>
</script>
<!-- Show product -->
<script id="productTemplate" type="text/x-jQuery-tmpl">
${name}
</script>
<!-- Show product on sale -->
<script id="productOnSaleTemplate" type="text/x-jQuery-tmpl">
<b>${name}</b> <img src="images/on_sale.png" alt="On Sale" />
</script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
var products = [
{ name: "Laptop", onSale: false },
{ name: "Apples", onSale: true },
{ name: "Comb", onSale: false }
];
$("#productListTemplate").tmpl(products).appendTo("#productListContainer");
</script>
</div>
</body>
</html>
In
the page above,
the main template used to display
the list of products looks like this:
<script id="productListTemplate" type="text/x-jQuery-tmpl">
<div>
{{if onSale}}
{{tmpl "#productOnSaleTemplate"}}
{{else}}
{{tmpl "#productTemplate"}}
{{/if}}
</div>
</script>
If a product is on sale then
the product is displayed with
the productOnSaleTemplate (which includes an on sale image):
<script id="productOnSaleTemplate" type="text/x-jQuery-tmpl">
<b>${name}</b> <img src="images/on_sale.png" alt="On Sale" />
</script>
Otherwise,
the product is displayed with
the normal productTemplate (which does not include
the on sale image):
<script id="productTemplate" type="text/x-jQuery-tmpl">
${name}
</script>
You can pass a parameter to
the {{tmpl}} tag.
The parameter becomes
the data passed to
the template rendered by
the {{tmpl}} tag.
For example, in
the previous section, we used
the {{each}} template tag to display a list of categories for each blog entry like this:
<script id="blogPostTemplate" type="text/x-jQuery-tmpl">
<h1>${postTitle}</h1>
<p>
${postEntry}
</p>
{{if categories}}
Categories: {{each categories}} <i>${$value}</i> {{/each}}
{{else}}
Uncategorized
{{/if}}
</script>
Another way to create this template is to use template composition like this:
<script id="blogPostTemplate" type="text/x-jQuery-tmpl">
<h1>${postTitle}</h1>
<p>
${postEntry}
</p>
{{if categories}}
Categories: {{tmpl(categories) "#categoryTemplate"}}
{{else}}
Uncategorized
{{/if}}
</script>
<script id="categoryTemplate" type="text/x-jQuery-tmpl">
<i>${$data}</i>
</script>
Using
the {{each}} tag or {{tmpl}} tag is largely a matter of personal preference.
Wrapped Templates
The {{wrap}} template tag enables you to take a chunk of HTML and transform
the HTML into another chunk of HTML (think easy XSLT). When you use
the {{wrap}} tag, you work with two templates.
The first template contains
the HTML being transformed and
the second template includes
the filter expressions for transforming
the HTML.
For example, you can use
the {{wrap}} template tag to transform a chunk of HTML into an interactive tab strip:
When you click any of
the tabs, you see
the corresponding content.
This tab strip was created with
the following page:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Wrapped Templates</title>
<style type="text/css">
body {
font-family: Arial;
background-color:black;
}
.tabs div {
display:inline-block;
border-bottom: 1px solid black;
padding:4px;
background-color:gray;
cursor:pointer;
}
.tabs div.tabState_true {
background-color:white;
border-bottom:1px solid white;
}
.tabBody {
border-top:1px solid white;
padding:10px;
background-color:white;
min-height:400px;
width:400px;
}
</style>
</head>
<body>
<div id="tabsView"></div>
<script id="tabsContent" type="text/x-jquery-tmpl">
{{wrap "#tabsWrap"}}
<h3>Tab 1</h3>
<div>
Content of tab 1.
Lorem ipsum dolor <b>sit</b> amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
</div>
<h3>Tab 2</h3>
<div>
Content of tab 2.
Lorem ipsum dolor <b>sit</b> amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
</div>
<h3>Tab 3</h3>
<div>
Content of tab 3.
Lorem ipsum dolor <b>sit</b> amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
</div>
{{/wrap}}
</script>
<script id="tabsWrap" type="text/x-jquery-tmpl">
<div class="tabs">
{{each $item.html("h3", true)}}
<div class="tabState_${$index === selectedTabIndex}">
${$value}
</div>
{{/each}}
</div>
<div class="tabBody">
{{html $item.html("div")[selectedTabIndex]}}
</div>
</script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
// Global for tracking selected tab
var selectedTabIndex = 0;
// Render
the tab strip
$("#tabsContent").tmpl().appendTo("#tabsView");
// When a tab is clicked, update
the tab strip
$("#tabsView")
.delegate(".tabState_false", "click", function () {
var templateItem = $.tmplItem(this);
selectedTabIndex = $(this).index();
templateItem.update();
});
</script>
</body>
</html>
The “source” for
the tab strip is contained in
the following template:
<script id="tabsContent" type="text/x-jquery-tmpl">
{{wrap "#tabsWrap"}}
<h3>Tab 1</h3>
<div>
Content of tab 1.
Lorem ipsum dolor <b>sit</b> amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
</div>
<h3>Tab 2</h3>
<div>
Content of tab 2.
Lorem ipsum dolor <b>sit</b> amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
</div>
<h3>Tab 3</h3>
<div>
Content of tab 3.
Lorem ipsum dolor <b>sit</b> amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
</div>
{{/wrap}}
</script>
The tab strip is created with a list of H3 elements (which represent each tab) and DIV elements (which represent
the body of each tab). Notice that
the HTML content is wrapped in
the {{wrap}} template tag. This template tag points at
the following tabsWrap template:
<script id="tabsWrap" type="text/x-jquery-tmpl">
<div class="tabs">
{{each $item.html("h3", true)}}
<div class="tabState_${$index === selectedTabIndex}">
${$value}
</div>
{{/each}}
</div>
<div class="tabBody">
{{html $item.html("div")[selectedTabIndex]}}
</div>
</script>
The tabs DIV contains all of
the tabs.
The {{each}} template tag is used to loop through each of
the H3 elements from
the source template and render a DIV tag that represents a particular tab.
The template item html() method is used to filter content from
the “source” HTML template.
The html() method accepts a jQuery selector for its first parameter.
The tabs are retrieved from
the source template by using an h3 filter.
The second parameter passed to
the html() method –
the textOnly parameter -- causes
the filter to return
the inner text of each h3 element. You can learn more about
the html() method at
the jQuery website (see
the section on $item.html()).
The tabBody DIV renders
the body of
the selected tab. Notice that
the {{html}} template tag is used to display
the tab body so that HTML content in
the body won’t be HTML encoded.
The html() method is used, once again, to grab all of
the DIV elements from
the source HTML template.
The selectedTabIndex global variable is used to display
the contents of
the selected tab.
Remote Templates
A common feature request for jQuery templates is support for remote templates. Developers want to be able to separate templates into different files.
Adding support for remote templates requires only a few lines of extra code (Dave Ward has a nice blog entry on this). For example,
the following page uses a remote template from a file named BookTemplate.htm:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Remote Templates</title>
<link href="0_Site.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="pageContent">
<h1>ASP.NET Bookstore</h1>
<div id="bookContainer"></div>
</div>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
// Create an array of books
var books = [
{ title: "ASP.NET 4 Unleashed", price: 37.79, picture: "AspNet4Unleashed.jpg" },
{ title: "ASP.NET MVC Unleashed", price: 44.99, picture: "AspNetMvcUnleashed.jpg" },
{ title: "ASP.NET Kick Start", price: 4.00, picture: "AspNetKickStart.jpg" },
{ title: "ASP.NET MVC Unleashed iPhone", price: 44.99, picture: "AspNetMvcUnleashedIPhone.jpg" },
];
// Get
the remote template
$.get("BookTemplate.htm", null, function (bookTemplate) {
// Render
the books using
the remote template
$.tmpl(bookTemplate, books).appendTo("#bookContainer");
});
function formatPrice(price) {
return "$" + price.toFixed(2);
}
</script>
</body>
</html>
The remote template is retrieved (and rendered) with
the following code:
// Get
the remote template
$.get("BookTemplate.htm", null, function (bookTemplate) {
// Render
the books using
the remote template
$.tmpl(bookTemplate, books).appendTo("#bookContainer");
});
This code uses
the standard jQuery $.get() method to get
the BookTemplate.htm file from
the server with an Ajax request. After
the BookTemplate.htm file is successfully retrieved,
the $.tmpl() method is used to render an array of books with
the template. Here’s what
the BookTemplate.htm file looks like:
<div>
<img src="BookPictures/${picture}" alt="" />
<h2>${title}</h2>
price: ${formatPrice(price)}
</div>
Notice that
the template in
the BooksTemplate.htm file is not wrapped by a SCRIPT element. There is no need to wrap
the template in this case because there is no possibility that
the template will get interpreted before you want it to be interpreted.
If you plan to use
the bookTemplate multiple times – for example, you are paging or sorting
the books -- then you should compile
the template into a function and cache
the compiled template function.
For example,
the following page can be used to page through a list of 100 products (using iPhone style More paging).
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Template Caching</title>
<link href="6_Site.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Products</h1>
<div id="productContainer"></div>
<button id="more">More</button>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
// Globals
var pageIndex = 0;
// Create an array of products
var products = [];
for (var i = 0; i < 100; i++) {
products.push({ name: "Product " + (i + 1) });
}
// Get
the remote template
$.get("ProductTemplate.htm", null, function (productTemplate) {
// Compile and cache
the template
$.template("productTemplate", productTemplate);
// Render
the products
renderProducts(0);
});
$("#more").click(function () {
pageIndex++;
renderProducts();
});
function renderProducts() {
// Get page of products
var pageOfProducts = products.slice(pageIndex * 5, pageIndex * 5 + 5);
// Used cached productTemplate to render products
$.tmpl("productTemplate", pageOfProducts).appendTo("#productContainer");
}
function formatPrice(price) {
return "$" + price.toFixed(2);
}
</script>
</body>
</html>
The ProductTemplate is retrieved from an external file named ProductTemplate.htm. This template is retrieved only once. Furthermore, it is compiled and cached with
the help of
the $.template() method:
// Get
the remote template
$.get("ProductTemplate.htm", null, function (productTemplate) {
// Compile and cache
the template
$.template("productTemplate", productTemplate);
// Render
the products
renderProducts(0);
});
The $.template() method compiles
the HTML representation of
the template into a JavaScript function and caches
the template function with
the name productTemplate.
The cached template can be used by calling
the $.tmp() method.
The productTemplate is used in
the renderProducts() method:
function renderProducts() {
// Get page of products
var pageOfProducts = products.slice(pageIndex * 5, pageIndex * 5 + 5);
// Used cached productTemplate to render products
$.tmpl("productTemplate", pageOfProducts).appendTo("#productContainer");
}
In
the code above,
the first parameter passed to
the $.tmpl() method is
the name of a cached template.
Working with Template Items
In this final section, I want to devote some space to discussing Template Items. A new Template Item is created for each rendered instance of a template. For example, if you are displaying a list of 100 products with a template, then 100 Template Items are created.
A Template Item has
the following properties and methods:
data –
The data associated with
the Template Instance. For example, a product.
tmpl –
The template associated with
the Template Instance.
parent –
The parent template item if
the template is nested.
nodes –
The HTML content of
the template.
calls – Used by {{wrap}} template tag.
nest – Used by {{tmpl}} template tag.
wrap – Used to imperatively enable wrapped templates.
html – Used to filter content from a wrapped template. See
the above section on wrapped templates.
update – Used to re-render a template item.
The last method –
the update() method -- is especially interesting because it enables you to re-render a template item with new data or even a new template.
For example,
the following page displays a list of books. When you hover your mouse over any of
the books, additional book details are displayed. In
the following screenshot, details for ASP.NET Kick Start are displayed.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Template Item</title>
<link href="0_Site.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="pageContent">
<h1>ASP.NET Bookstore</h1>
<div id="bookContainer"></div>
</div>
<script id="bookTemplate" type="text/x-jQuery-tmpl">
<div class="bookItem">
<img src="BookPictures/${picture}" alt="" />
<h2>${title}</h2>
price: ${formatPrice(price)}
</div>
</script>
<script id="bookDetailsTemplate" type="text/x-jQuery-tmpl">
<div class="bookItem">
<img src="BookPictures/${picture}" alt="" />
<h2>${title}</h2>
price: ${formatPrice(price)}
<p>
${description}
</p>
</div>
</script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.js"></script>
<script type="text/javascript">
// Create an array of books
var books = [
{ title: "ASP.NET 4 Unleashed", price: 37.79, picture: "AspNet4Unleashed.jpg", description: "
The most comprehensive book on Microsoft’s new ASP.NET 4.. " },
{ title: "ASP.NET MVC Unleashed", price: 44.99, picture: "AspNetMvcUnleashed.jpg", description: "Writing for professional programmers, Walther explains
the crucial concepts that make
the Model-View-Controller (MVC) development paradigm work…" },
{ title: "ASP.NET Kick Start", price: 4.00, picture: "AspNetKickStart.jpg", description: "Visual Studio .NET is
the premier development environment for creating .NET applications…." },
{ title: "ASP.NET MVC Unleashed iPhone", price: 44.99, picture: "AspNetMvcUnleashedIPhone.jpg", description: "ASP.NET MVC Unleashed for
the iPhone…" },
];
// Render
the books using
the template
$("#bookTemplate").tmpl(books).appendTo("#bookContainer");
// Get compiled details template
var bookDetailsTemplate = $("#bookDetailsTemplate").template();
// Add hover handler
$(".bookItem").mouseenter(function () {
// Get template item associated with DIV
var templateItem = $(this).tmplItem();
// Change template to compiled template
templateItem.tmpl = bookDetailsTemplate;
// Re-render template
templateItem.update();
});
function formatPrice(price) {
return "$" + price.toFixed(2);
}
</script>
</body>
</html>
There are two templates used to display a book: bookTemplate and bookDetailsTemplate. When you hover your mouse over a template item,
the standard bookTemplate is swapped out for
the bookDetailsTemplate.
The bookDetailsTemplate displays a book description.
The books are rendered with
the bookTemplate with
the following line of code:
// Render
the books using
the template
$("#bookTemplate").tmpl(books).appendTo("#bookContainer");
The following code is used to swap
the bookTemplate and
the bookDetailsTemplate to show details for a book:
// Get compiled details template
var bookDetailsTemplate = $("#bookDetailsTemplate").template();
// Add hover handler
$(".bookItem").mouseenter(function () {
// Get template item associated with DIV
var templateItem = $(this).tmplItem();
// Change template to compiled template
templateItem.tmpl = bookDetailsTemplate;
// Re-render template
templateItem.update();
});
When you hover your mouse over a DIV element rendered by
the bookTemplate,
the mouseenter handler executes. First, this handler retrieves
the Template Item associated with
the DIV element by calling
the tmplItem() method.
The tmplItem() method returns a Template Item.
Next, a new template is assigned to
the Template Item. Notice that a compiled version of
the bookDetailsTemplate is assigned to
the Template Item’s tmpl property.
The template is compiled earlier in
the code by calling
the template() method.
Finally,
the Template Item update() method is called to re-render
the Template Item with
the bookDetailsTemplate instead of
the original bookTemplate.
Summary
This is a long blog entry and I still have not managed to cover all of
the features of jQuery Templates J However, I’ve tried to cover
the most important features of jQuery Templates such as template composition, template wrapping, and template items.
To learn more about jQuery Templates, I recommend that you look at
the documentation for jQuery Templates at
the official jQuery website. Another
great way to learn more about jQuery Templates is to look at
the (unminified) source code.
