Windows Store App Development Series: Part 19 – WinJS Promise Object Chaining

Hello,

In the previous article of this series, we have seen how to make asynchronous call to external web service using WinJS Promise object. We also explored WinJS.xhr function execution pattern [success, error, progress]. In real-life application, one might want to make a web service call dependent on previous web service call. WinJS Promise object provides easy way to chain such calls to external components. Purpose of this article is to explain WinJS Promise object chaining with code example off course!

Before we dive into the code, lets revisit promise.done method explained in previous article, and how it differs from promise.then method, which is primary used for chaining.

Both promise.done and promise.then methods allows you to specify the work to be done on the fulfillment of promised value [call to external service / component in asynchronous manner], error handling that needs to be performed in case of any exception and finally a way to handle progress notification. The only difference is that promise.done method returns undefined and promise.then method returns a promise object so that you can chain it further.

Lets understand the syntax differences.

promise.done syntax

promise.done(onComplete, onError, onProgress);

promise.then syntax

var promise = promise.then(onComplete, onError, onProgress);

In both the cases -

  • OnComplete parameter is a JavaScript function which gets called if the promise is fulfilled, for e.g. call to external service successfully done.
  • onError function gets called if the promise is fulfilled with an error, for e.g. call to external service failed.
  • onProgress function reports the progress of the promise. During a time consuming asynchronous call, this function might get called multiple times to return the progress to caller.

Now we understand the basic differences between two functions, lets build a Windows Store App and implement promise object chaining. The purpose of the app is to extract customer information [name, address, city, country etc] from Northwind Odata service and display it in a WinJS ListView control. As you might have guessed its a two step process [extract information and display information], we will use WinJS promise object chaining pattern.

  1. Create a Windows Store App using JavaScript – Blank App template as shown in below screenshot01 Blank App
  2. Since we need to display customer information in a list format, declare a ListView object in default.html file and bind it to a ListView template as shown in below.
    <body>
        <div id="customerListViewTemplate"
            data-win-control="WinJS.Binding.Template">
            <div class="itemContainer">
                <div class="itemContactName" data-win-bind="innerText:ContactName"></div>
                <div>
                    <span data-win-bind="innerText:Address"></span> <br>
                    <span data-win-bind="innerText:City"></span> <br>
                    <span data-win-bind="innerText:PostalCode"></span>
                </div>
                <div class="itemCountry" data-win-bind="innerText:Country"></div>
            </div>
        </div>
    
        <div id="customerListView"
            data-win-control="WinJS.UI.ListView"
            data-win-options="{itemTemplate: select('#customerListViewTemplate')}">
        </div>
    </body>
    
  3. Next, we need to extract customer information using Northwind OData service and populate the ListView control. In default.js file, add the code defined below for app.onactivated event.

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
    
            WinJS.xhr({ url: "http://services.odata.org/V3/Northwind/Northwind.svc/Customers" })
                 .then(SaveCustomerData)
                 .done(DisplayCustomerData);
    
            args.setPromise(WinJS.UI.processAll());
        }
    };
    

    WinJS.xhr function is set to make an asynchronous call to Northwind OData service. Since XHR function returns a WinJS Promise object, we can directly chain it by calling .then syntax which is set to call SaveCustomerData JavaScript function. Since .then function itself returns WinJS Promise object again, we are chaining it further using .done syntax, which is set to call DisplayCustomerData JavaScript function.

  4. As the function name suggests SaveCustomerData function simply persists XHR response information in a local variable result. Note, you can implement any complex logic like persisting information to database, calling external service here. For the purpose of this app, I am just storing it in a local variable.

    function SaveCustomerData(response) {
        var result = response.responseXML;
    }
    
  5. DisplayCustomerInformation function iterates over result variable which contains customer information and populates customerList array. WinJS.Binding.List converts array to a binding list and binds it to customerListView declared in default.html file.

    function DisplayCustomerData() {
        var items = result.querySelectorAll("entry");
    
        for (var ctr = 0; ctr < items.length; ctr++) {
            var customer = {};
            customer.ContactName = items[ctr].querySelector("ContactName").textContent;
            customer.Address = items[ctr].querySelector("Address").textContent;
            customer.City = items[ctr].querySelector("City").textContent;
            customer.PostalCode = items[ctr].querySelector("PostalCode").textContent;
            customer.Country = items[ctr].querySelector("Country").textContent;
            customerList.push(customer);
        }
    
        dataList = new WinJS.Binding.List(customerList);
        var customerListView = document.getElementById('customerListView').winControl;
        customerListView.itemDataSource = dataList.dataSource;
    }
    
  6. That’s all! Modify default.css file as you like and run the application. You should get output as shown in below screenshot.
    Northwind OData Service Customer List

Summary

In this article we analyzed WinJS promise object chaining. We briefly discussed differences between promise.done and promise.then method and finally built a nice app to extract customer information using Northwind OData service.

I hope it was useful to you.

Thanks for reading.

Download Source Code

Complete source code of this series is available on GitHub.

Leave a Reply