Metro: Using Templates

The goal of this blog post is to describe how templates work in the WinJS library. In particular, you learn how to use a template to display both a single item and an array of items. You also learn how to load a template from an external file.

Why use Templates?

Imagine that you want to display a list of products in a page. The following code is bad:

var products = [
    { name: "Tesla", price: 80000 },
    { name: "VW Rabbit", price: 200 },
    { name: "BMW", price: 60000 }
];

var productsHTML = "";
for (var i = 0; i < products.length; i++) {
    productsHTML += "<h1>Product Details</h1>"
        + "<div>Product Name: " + products[i].name + "</div>"
        + "<div>Product Price: " + products[i].price + "</div>";
}

document.getElementById("productContainer").innerHTML = productsHTML;

In the code above, an array of products is displayed by creating a for..next loop which loops through each element in the array. A string which represents a list of products is built through concatenation.

The code above is a designer’s nightmare. You cannot modify the appearance of the list of products without modifying the JavaScript code.

A much better approach is to use a template like this:

<div id="productTemplate">
    <h1>Product Details</h1>
    <div>
        Product Name:
        <span data-win-bind="innerText:name"></span>
    </div>
    <div>
        Product Price:
        <span data-win-bind="innerText:price"></span>
    </div>
</div>

A template is simply a fragment of HTML that contains placeholders. Instead of displaying a list of products by concatenating together a string, you can render a template for each product.

Creating a Simple Template

Let’s start by using a template to render a single product. The following HTML page contains a template and a placeholder for rendering the template:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Application1</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
    <script src="//Microsoft.WinJS.0.6/js/base.js"></script>
    <script src="//Microsoft.WinJS.0.6/js/ui.js"></script>

    <!-- Application1 references -->
    <link href="http://3a0ojxkezud2pogen3j4z0w18nq.wpengine.netdna-cdn.com/css/default.css" rel="stylesheet">
    <script src="http://3a0ojxkezud2pogen3j4z0w18nq.wpengine.netdna-cdn.com/js/default.js"></script>
</head>
<body>


    <!-- Product Template -->
    <div id="productTemplate">
        <h1>Product Details</h1>
        <div>
            Product Name:
            <span data-win-bind="innerText:name"></span>
        </div>
        <div>
            Product Price:
            <span data-win-bind="innerText:price"></span>
        </div>
    </div>

    <!-- Place where Product Template is Rendered -->
    <div id="productContainer"></div>



</body>
</html>

In the page above, the template is defined in a DIV element with the id productTemplate. The contents of the productTemplate are not displayed when the page is opened in the browser. The contents of a template are automatically hidden when you convert the productTemplate into a template in your JavaScript code.

Notice that the template uses data-win-bind attributes to display the product name and price properties. You can use both data-win-bind and data-win-bindsource attributes within a template. To learn more about these attributes, see my earlier blog post on WinJS data binding:

http://stephenwalther.com/blog/archive/2012/02/26/windows-web-applications-declarative-data-binding.aspx

The page above also includes a DIV element named productContainer. The rendered template is added to this element.

Here’s the code for the default.js script which creates and renders the template:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {

            var product = {
                name: "Tesla",
                price: 80000
            };

            var productTemplate = new WinJS.Binding.Template(document.getElementById("productTemplate"));
            productTemplate.render(product, document.getElementById("productContainer"));

        }
    };


    app.start();
})();




In the code above, a single product object is created with the following line of code:

var product = {

   name: "Tesla",

   price: 80000

};


Next, the productTemplate element from the page is converted into an actual WinJS template with the following line of code:

var productTemplate = new WinJS.Binding.Template(document.getElementById("productTemplate"));

The template is rendered to the templateContainer element with the following line of code:

productTemplate.render(product, document.getElementById("productContainer"));

The result of this work is that the product details are displayed:

clip_image002

Notice that you do not need to call WinJS.Binding.processAll(). The Template render() method takes care of the binding for you.

Displaying an Array in a Template

If you want to display an array of products using a template then you simply need to create a for..next loop and iterate through the array calling the Template render() method for each element.

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {

            var products = [
                { name: "Tesla", price: 80000 },
                { name: "VW Rabbit", price: 200 },
                { name: "BMW", price: 60000 }
            ];

            var productTemplate = new WinJS.Binding.Template(document.getElementById("productTemplate"));
            var productContainer = document.getElementById("productContainer");

            var i, product;
            for (i = 0; i < products.length; i++) {
                product = products[i];
                productTemplate.render(product, productContainer);
            }
        }
    };


    app.start();
})();

After each product in the array is rendered with the template, the result is appended to the productContainer element.

clip_image004

No changes need to be made to the HTML page discussed in the previous section to display an array of products instead of a single product. The same product template can be used in both scenarios.

Rendering an HTML TABLE with a Template

When using the WinJS library, you create a template by creating an HTML element in your page. One drawback to this approach of creating templates is that your templates are part of your HTML page. In order for your HTML page to validate, the HTML within your templates must also validate.

This means, for example, that you cannot enclose a single HTML table row within a template. The following HTML is invalid because you cannot place a TR element directly within the body of an HTML document:

 

<!-- Product Template -->

<tr>

   <td data-win-bind="innerText:name"></td>

   <td data-win-bind="innerText:price"></td>

</tr>


This template won’t validate because, in a valid HTML5 document, a TR element must appear within a THEAD or TBODY element. Instead, you must create the entire TABLE element in the template. The following HTML page illustrates how you can create a template which contains a TR element:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Application1</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
    <script src="//Microsoft.WinJS.0.6/js/base.js"></script>
    <script src="//Microsoft.WinJS.0.6/js/ui.js"></script>

    <!-- Application1 references -->
    <link href="http://3a0ojxkezud2pogen3j4z0w18nq.wpengine.netdna-cdn.com/css/default.css" rel="stylesheet">
    <script src="http://3a0ojxkezud2pogen3j4z0w18nq.wpengine.netdna-cdn.com/js/default.js"></script>
</head>
<body>


    <!-- Product Template -->
    <div id="productTemplate">
    <table>
    <tbody>
    <tr>
        <td data-win-bind="innerText:name"></td>
        <td data-win-bind="innerText:price"></td>
    </tr>
    </tbody>
    </table>
    </div>

    <!-- Place where Product Template is Rendered -->
    <table>
        <thead>
            <tr>
                <th>Name</th><th>Price</th>
            </tr>
        </thead>
        <tbody id="productContainer">
        </tbody>
    </table>


</body>
</html>

 

In the HTML page above, the product template includes TABLE and TBODY elements:

<!-- Product Template -->
<div id="productTemplate">
<table>
<tbody>
<tr>
    <td data-win-bind="innerText:name"></td>
    <td data-win-bind="innerText:price"></td>
</tr>
</tbody>
</table>
</div>

We discard these elements when we render the template. The only reason that we include the TABLE and THEAD elements in the template is to make the HTML page validate as valid HTML5 markup.

Notice that the productContainer (the target of the template) in the page above is a TBODY element. We want to add the rows rendered by the template to the TBODY element in the page.

The productTemplate is rendered in the default.js file:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {

            var products = [
                { name: "Tesla", price: 80000 },
                { name: "VW Rabbit", price: 200 },
                { name: "BMW", price: 60000 }
            ];

            var productTemplate = new WinJS.Binding.Template(document.getElementById("productTemplate"));
            var productContainer = document.getElementById("productContainer");


            var i, product, row;
            for (i = 0; i < products.length; i++) {
                product = products[i];
                productTemplate.render(product).then(function (result) {
                    row = WinJS.Utilities.query("tr", result).get(0);
                    productContainer.appendChild(row);
                });
            }


        }
    };


    app.start();
})();




When the product template is rendered, the TR element is extracted from the rendered template by using the WinJS.Utilities.query() method. Next, only the TR element is added to the productContainer:

productTemplate.render(product).then(function (result) {
    row = WinJS.Utilities.query("tr", result).get(0);
    productContainer.appendChild(row);
});

I discuss the WinJS.Utilities.query() method in depth in a previous blog entry:

http://stephenwalther.com/blog/archive/2012/02/23/windows-web-applications-query-selectors.aspx

When everything gets rendered, the products are displayed in an HTML table:

clip_image006

You can see the actual HTML rendered by looking at the Visual Studio DOM Explorer window:

image

 

Loading an External Template

Instead of embedding a template in an HTML page, you can place your template in an external HTML file. It makes sense to create a template in an external file when you need to use the same template in multiple pages. For example, you might need to use the same product template in multiple pages in your application.

The following HTML page does not contain a template. It only contains a container that will act as a target for the rendered template:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Application1</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
    <script src="//Microsoft.WinJS.0.6/js/base.js"></script>
    <script src="//Microsoft.WinJS.0.6/js/ui.js"></script>

    <!-- Application1 references -->
    <link href="http://3a0ojxkezud2pogen3j4z0w18nq.wpengine.netdna-cdn.com/css/default.css" rel="stylesheet">
    <script src="http://3a0ojxkezud2pogen3j4z0w18nq.wpengine.netdna-cdn.com/js/default.js"></script>
</head>
<body>

    <!-- Place where Product Template is Rendered -->
    <div id="productContainer"></div>

</body>
</html>

The template is contained in a separate file located at the path /templates/productTemplate.html:

image

 

Here’s the contents of the productTemplate.html file:

<!-- Product Template -->
<div id="productTemplate">
    <h1>Product Details</h1>
    <div>
        Product Name:
        <span data-win-bind="innerText:name"></span>
    </div>
    <div>
        Product Price:
        <span data-win-bind="innerText:price"></span>
    </div>
</div>

Notice that the template file only contains the template and not the standard opening and closing HTML elements. It is an HTML fragment.

If you prefer, you can include all of the standard opening and closing HTML elements in your external template – these elements get stripped away automatically:

<html>
    <head><title>product template</title></head>
    <body>

    <!-- Product Template -->
    <div id="productTemplate">
        <h1>Product Details</h1>
        <div>
            Product Name:
            <span data-win-bind="innerText:name"></span>
        </div>
        <div>
            Product Price:
            <span data-win-bind="innerText:price"></span>
        </div>
    </div>

    </body>
</html>

Either approach – using a fragment or using a full HTML document  — works fine.

Finally, the following default.js file loads the external template, renders the template for each product, and appends the result to the product container:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {


            var products = [
                { name: "Tesla", price: 80000 },
                { name: "VW Rabbit", price: 200 },
                { name: "BMW", price: 60000 }
            ];

            var productTemplate = new WinJS.Binding.Template(null, { href: "/templates/productTemplate.html" });
            var productContainer = document.getElementById("productContainer");


            var i, product, row;
            for (i = 0; i < products.length; i++) {
                product = products[i];
                productTemplate.render(product, productContainer);
            }
        }
    };


    app.start();
})();




The path to the external template is passed to the constructor for the Template class as one of the options:

var productTemplate = new WinJS.Binding.Template(null, {href:"/templates/productTemplate.html"});

When a template is contained in a page then you use the first parameter of the WinJS.Binding.Template constructor to represent the template – instead of null, you pass the element which contains the template. When a template is located in an external file, you pass the href for the file as part of the second parameter for the WinJS.Binding.Template constructor.

Summary

The goal of this blog entry was to describe how you can use WinJS templates to render either a single item or an array of items to a page. We also explored two advanced topics. You learned how to render an HTML table by extracting the TR element from a template. You also learned how to place a template in an external file.

Discussion

  1. Cen says:

    Hi, one small suggestion: it is harder to read shaded text (code samples). Looks blurry and I am constantly squeezing my eyes, trying to focus my eyes, but of course it is of no help 🙂

  2. @Cen — Hit Refresh/Reload on your browser and you should get the updated style sheet with the lighter background color for the code. Thanks for letting me know.

  3. Andrey says:

    Tahnks for the great series about WinJS! Is it possible to make whole table as a template and then just bind values array to it? I think it is easier to use than manually append every node.

    • The problem is that WinJS does not support a foreach syntax which you can use within a template. The current version does not have a way to create nested templates or iterate through data items within a template. These were nice features of the jQuery Templates plugin.

  4. Stilgar says:

    I find it extremely frustrating that you can’t put the item template in the container (like you can in ASP.NET for example). What is more if the template is an external file you can’t even find it without checking the JS code. Or maybe I missed something?

    Correct me if I am wrong but the JQuery databinding contributed to JQuery by Microsoft not only supports two-way databinding but also supports in-place item templates.

    • That’s right — the jQuery databinding plugin supported two-way databinding and the jQuery templates plugin supported creating in-place nested templates.