Often you need to display a list of items in a application. The Windows Library for JavaScript contains a ListView control for you to use in your applications. The control can be bound to a data source and templated from HTML.

Getting started

We’ll start off by creating a new project and choosing the Fixed Layout Application project template.

As you can see, the template has added a paragraph (p) to the tree which contains some text. You can use that to place the title of your application. The ListView is going to be in the same div as that paragraph.

You can add the ListView by hand, typing the HTML, but I personally prefer dragging and dropping controls onto the designer. Select the parent div of the paragraph. 

Type ListView in the search box of the Assets panel and drag the result from the list to the design surface.

If you switch to Split view in the designer you can see the HTML …

which should contain the following element.

<div data-win-control="WinJS.UI.ListView"></div>

To be able to write code against the ListView it has to have an Id. You can enter this on the Attributes panel. In this case I named the ListView “posts”.

Getting Data

The ListView in this demo application is going to display the Atom feed from this blog. The Windows Library makes this very easy.

Have a look at default.js in your solution. This file contains some code to get you started. When the window is activated the onmainwindowsactivated function is called. This is where the retrieval of the atom feed has to be initiated. First create a new AtomPubClient and a Uri to the feed. Than, pass the url to the retreiveFeedAsync function and have it process the posts or handle the error. At the end of the function you have to call processAll to have all declarative bindings applied on the controls. This is needed to get the templating to work which we’ll create in a second.

I haven’t implemented error handling in the demo, only an empty function. The processPosts function will be implemented after the templated.

WinJS.Application.onmainwindowactivated = function (e) {
    if (e.detail.kind ===
     Windows.ApplicationModel.Activation.ActivationKind.launch) {

        var syn = new Windows.Web.AtomPub.AtomPubClientClient();
        var url =
           new Windows.Foundation.Uri("http://timmykokke.com/atom");
        syn.retrieveFeedAsync(url)
           .then(processPosts, downloadError);

        WinJS.UI.processAll();
    }
}

function downloadError() {
    // handle error
}

Creating a template

The template is created in HTML. It’s basically a div with the data-win-control set like the ListView. The children of that div are used as a template for the ListView.  The template has to be defined before the ListView. To get the bindings to work you’ll have to add the binding.js script to the head section of the HTML file.

The actual binding is done by adding the data-win-control attribute to the divs inside the template. In this case the innerText property of the div is bound to the title property of the data bound object. Note that the children of the template are not shown in the Live DOM panel.

I’ll demonstrate how to set the classes later.

<script src="/winjs/js/binding.js"></script>
...
<div id="itemTemplate" data-win-control="WinJS.Binding.Template" >
    <div class="post">
        <div class="title" data-win-bind="innerText: title"></div>
        <div class="summary" data-win-bind="innerText: summary"></div>
        <div class="date" data-win-bind="innerText: date"></div>
    </div>
</div>
<div id="posts" data-win-control="WinJS.UI.ListView" ></div>

To make the template known to the ListView, select it and go to the Attributes panel. Enter the name of the template in the textbox next to the itemRenderer property. In this case the templated is named itemTemplate.

Process feed

The feed returned by the earlier code has to be processed to match the template. It’s nothing more than creating an array (myDataSource), run over the items, adding anonymous objects to the array and setting the data source of the posts to it. If you would like to do some custom formatting on the items, like changing the date to something more readable for example, you can do that here.

function processPosts(feed) {
    var myDataSource = [];

    for (var i = 0, len = feed.items.length; i < len; i++) {
        var item = feed.items[i];
        myDataSource.push({
            title:   item.title.text,
            summary: item.summary.text,
            date:    item.publishedDate
         });
     }

     posts.winControl.dataSource = myDataSource;
}

One of the great things of working with Blend is that you do not have to run your application to see the result and work with it. Try hitting CTRL+R or click on the refresh button in the top right corner of the designer.

If all code is correct you should see the ListView filled with titles and summaries. The Live DOM panel should be filled with elements now. The elements that are generated by code are added to the list to. These elements are marked with a small lightning  bold icon.

Now we have to make sure the ListView is showing a ListLayout. With the posts element selected in the Live DOM panel head over to the Attributes panel. Look for the layout property and hit the button next to it.

Select ListLayout from the list and hit Ok. Refresh the design if needed.

CSS for template

Now we have the ListView filled with data we can set the templates.

Try selecting a title of one of the posts. You might have to click a couple of times, and notice that with every click you drill a little deeper in the element tree.

With the element selected head over to the CSS Properties panel. Click on the little triangle and select Create style rule from selected element class… and title.

This will create a CSS style rule in default.css for the title class. It is automatically selected. Try changing some of its properties, for example the text color and font-size and see what happens. The height and margins of the programmatically added items is not recalculated on every change, so you may want to hit the refresh button every now and then to update it.

You can repeat the process for the summary and date template items too.

To see what items in the designer are affected by a CSS style rule, select one on the Styles panel. For example the .title rule. Notice how all titles got a green border in the designer and the elements in the Live DOM panel got a dark green background.

Wrap up

I hope that this tutorial has given you a start on how to use the ListView and how to use templating in Expression Blend. Other controls work in pretty much the same way. Feel free to drop my a line if you have any questions regarding this tutorial or anything else you run into.

For future tutorials on Expression Blend please subscribe to the rss feed or follow me on Twitter (@Sorskoot).