Handling multiple promises (HTML)

[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]

You can use WinJS.Promise.join to handle multiple promises.

WinJS.Promise.join allows you to handle the promises one at a time, if necessary, and also to do further handling after all the promises are completed.

In this topic, you'll learn how to join multiple promises and iterate over the results.

To create the project

In Windows Runtime apps , you need to add certain capabilities, such as accessing a particular library on your hard drive or accessing the network, if you want to perform them. For more info about capabilities, see App capability declarations.

• Create a blankJavaScript app.

To join promises

To demonstrate how to join promises, we'll set up a simple app that starts requesting Web pages when you click the Start button and stops it when you click the Stop button.

1. In the app you just created, open "default.html " and add Start and Stop buttons.

   <button id="start">Start</button>
   <button id="stop">Stop</button>
   

2. Add a DIV element to report on the files uploaded, and give it an ID of "outputDiv".

   <div id="outputDiv"></div>
   

3. In the app.onactivated event handler in "default.js" (/js/default.js), add event handlers for the Start and Stop buttons to start and cancel the upload process.

   app.onactivated = function (args) {
       document.getElementById("start").addEventListener("click", startUpload, false);
       document.getElementById("stop").addEventListener("click", stopUpload, false); 
    };
   

4. Create the event handlers.

   function startUpload() { }
   function stopUpload() { }
   

5. To handle multiple promises, you use WinJS.Promise.join, which takes a set of promises and itself returns a promise. You can use Array.map to return the array of promises used in WinJS.Promise.join. In the Array.map callback function, you return the promise that results from creating and starting the file upload.

   In this example, you notify the app when a request has been completed by writing to the DIV, and you report errors in the same place.

   // This variable is used to cancel the upload operation.
   var downloading = null;
   
   function startUpload() {
   
       var urls = [
           "https://www.microsoft.com",
           "https://www.msdn.microsoft.com",
           "https://www.windows.microsoft.com",
           "https://www.office.microsoft.com"
       ];
   
       var xhrs = urls.map(function (url) {
           return WinJS.xhr({ url: url });
       });
   
       downloading = WinJS.Promise.join(xhrs).
           then(function (files) {
               for (var file in files) {
                   picDiv.textContent = files[file].responseText;
               }
           });
   }
   

6. Try running the app now. You should see the Start and Stop buttons. If you click the Start button, the raw HTML of the Web pages should be displayed. The Stop button, of course, still doesn't do anything. You'll see how to cancel the process in the next section.

To cancel the promises

You can cancel the process by simply calling cancel on the upload process you created in the previous section.

1. Use the upload variable that you created in the previous code example to call cancel.

   function stopUpload() {
       if (uploading) {
           uploading.cancel();
       }
   }
   

2. Try running the app again. You should be able to start the upload process by using the Start button and stop it by using the Stop button.