Quickstart: Adding repeater controls

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how to use the Repeater control in Windows apps using JavaScript that displays a discrete set of data as repeating HTML markup.

The Repeater control, although similar to the ListView control in that it allows you to bind data to the HTML of your app, has several differences. It is ideal for smaller, finite, static sets of data that require less functionality to users. If connected to a dynamic data set, the Repeater is best suited for small, infrequent changes that are controlled by the developer. Furthermore, you can easily style the Repeater control with a small set of Cascading Style Sheets (CSS) rules.

Prerequisites

Create a new project by using the Blank App template

  1. Start Microsoft Visual Studio Express 2013 for Windows.

  2. From the Start Page tab, click New Project. The New Project dialog opens.

  3. In the Installed pane, expand Templates and JavaScript, and click the Windows Store app template type. The available project templates for JavaScript are displayed in the center pane of the dialog.

  4. In the center pane, pick the Blank App project template.

  5. In the Name text box, type Repeater demo.

  6. Click OK to create the project.

Add the repeater definition to the project

The Repeater control can be defined either declaratively in an HTML page or at run time using JavaScript loaded with the page. This example creates the repeater declaratively in the HTML markup.

  1. Open default.html and insert the following HTML into the <body> element. The hub should be a direct child of the <body> element.

    <div id="main-content">
    <h1>Great literature of Ancient Athens</h1>
    <div id="repeater" data-win-control="WinJS.UI.Repeater"
        data-win-options="{ data: Books.data }">
        <section>
            <h2 data-win-bind="textContent: bookTitle"></h2>
            <p><i data-win-bind="textContent: author"></i></p>
            <p data-win-bind="textContent: synopsis"></p>
        </section>
    </div>
</div>

  2. In default.html, inside the <head> tags, add the following <script> tags.

    <script src="/js/books.js"></script>

  3. In Solution Explorer, right-click the js folder, and then click Add > New JavaScript File. In the Add New Item dialog box, name the new JavaScript file "books.js" and then click Add.

  4. Open the books.js file (js/books.js) and add the following JavaScript code.

    (function () {
    "use strict";

    // Define a data set as an array of objects.
    var books = [
        {
            bookTitle: "Anabasis",
            author: "Xenophon",
            synopsis: "10,000 Greek mercenaries, lost in Persia, work together to make their way home."
        },
        {
            bookTitle: "History of the Peloponnesian War",
            author: "Thucydides",
            synopsis: "The mighty cities Sparta and Athens war for supremacy over the Hellenes."
        },
        {
            bookTitle: "Antigone",
            author: "Sophocles",
            synopsis: "A young woman defies the king of the city by giving her father a proper burial."
        }
    ];

    // Convert the array into a List object.
    var booksList = new WinJS.Binding.List(books);

    // Expose the list globally in the 'Books' namespace.
    WinJS.Namespace.define("Books",
        { data: booksList });

})();

  5. Press F5 to run the sample.

    The app displays three sections, each containing some data from the List exposed by the Books.data property.

In this example, the HTML fragment to be repeated is contained within the Repeater control declared in the HTML markup. (You can also use a WinJS.Binding.Template to define the repeating HTML fragment.) The Repeater control in the example presents items contained in the Books.data list, where each item from the List object is displayed in its own HTML fragment.

Summary and next steps

In this quickstart, you added a Repeater with three repeated HTML fragments, using a simple static data source.

For more information on how to dynamically add or remove data to a Repeater control, see the HTML Repeater control sample.