jQuery and WinJS working together in Windows Store apps

The Windows Library for JavaScript (WinJS) and Visual Studio templates for Windows Store apps give developers great flexibility when using third-party JavaScript libraries, including the popular jQuery. Many modern web developers use jQuery for quick, easy, and powerful DOM access and manipulation.

As we announced in April, you can use jQuery release 2.0 in a Windows Store app without getting errors related to the JavaScript runtime or dynamic content. In this post, I’ll show how you can apply jQuery to your Windows Store app. In addition, I’ll also look at some areas where WinJS provides compelling alternatives to specific jQuery APIs.

(If you want a refresher on the jQuery APIs, take a look at the jQuery documentation. You might also take a minute to remind yourself about how to use CSS selectors.)

Using jQuery in Windows Store apps

You need a local version of jQuery in your Window Store app, so you’ll need to download a copy of jQuery release 2.0 (or higher). After you have a copy of the jQuery library, add it to your JavaScript project in Visual Studio 2012 (right-click the ‘js’ folder in the project, click Add > Existing Item, and then select the jQuery library from where you saved it.)

(You can also get jQuery directly into your Visual Studio solution using NuGet.)

Next, you’ll need to reference the jQuery library in the HTML files for your app. Note that you’ll need to include a reference to jQuery on any HTML page that references a JavaScript file that uses jQuery. I recommend placing the reference in the starting page for the app (usually ‘default.html’), which ensures that you can use jQuery from any page loaded into (navigated from) that page.

<script src="/js/jquery-2.0.0.min.js"></script>

Basic DOM manipulation

The jQuery selector function (‘$’, also known simply as ‘the jQuery function’) comes in really handy when you need to access the DOM in an HTML document – including the markup that makes up the content of a Windows Store app. jQuery also provides a substantial library of APIs with various functions for manipulating HTML content and JavaScript data. From applying CSS styles to storing hidden data as JSON objects, jQuery has a wealth of tools you can use within your Windows Store app.

As an aside, if you just want the CSS selector function, you don’t need all of jQuery. Instead, you might try the Sizzle library: it’s free, open-source, and small. (In fact, the jQuery function was built upon Sizzle.) Sizzle also uses CSS selectors to return collections of HTML elements from the DOM. To use Sizzle, download a local copy of the library, add it to your project, and include a reference to the library in your HTML page (just like jQuery).

Now we can get down to business: using jQuery in a Windows Store app! The jQuery functions and techniques that you’ve become familiar with are available to your Windows Store app:

• You can get access to one or many elements in the app, with a fine degree of precision:
  

  var appHeadings = $('h1');
  var appContent = $('#app-content')[0];
  var formFields = $('form input[type="text"]');
  

 

• You can add event handlers to one (or many) elements in the app:
  

  $('.data').mouseover(function (event) { 
      // Some handler code.
  });
  $('#my-button').click(function (event) { 
      // Some handler code.
  });
  

• You can get the value of a select element in the app:
  

  var name = $("select option:selected").val();

• You can dynamically add HTML content to your app:
  

  $("#my-list").append("<li>A new list item.</li>");
  $("h1").html("My App Name");
  

• You can even dynamically style the HTML content in your app:
  

  $(".legal").css("font-size", "12pt");

With the jQuery functions, you can write terser, yet more powerful code for your Windows Store app. You can spend more time building features rather than trying to manipulate the UI.

Best yet, you can use the APIs provided by WinJS along with jQuery to create more elegant solutions. WinJS provides access to specific Windows features that jQuery can’t access on its own. Together, the two libraries can enable fluid, responsive, and beautiful apps. We’ll take a look at two specific scenarios for using jQuery in a Windows Store app: building an AppBar for navigation and selecting/storing data from a ListView control.

Creating an app navigation bar

To build a WinJS.UI.AppBar in a Windows Store app, we would declare the AppBar in the app’s HTML like so, specifying top placement as is used for navigation:

<div id="appbar" data-win-control="WinJS.UI.AppBar"
data-win-options="{layout: 'commands', placement: 'top'}">
<button data-win-control="WinJS.UI.AppBarCommand" 
data-win-options="{id: 'back', icon: 'back'}"
value="/html/pageone.html">
</button>
<button data-win-control="WinJS.UI.AppBarCommand" 
data-win-options="{id: 'favorite', icon: 'favorite'}"
value="/html/pagetwo.html">
</button>
<button data-win-control="WinJS.UI.AppBarCommand" 
data-win-options="{id: 'forward', icon: 'forward'}"
value="/html/pagethree.html">
</button>
</div>

Let’s assume that we want to define the behavior for the app bar as such: when a button is clicked, the app navigates to a specific page and the button that raised the event is disabled. All other buttons are enabled. Without jQuery, we might create this behavior with the following code, where we’re attaching the same handler to each command in the navigation bar:

// Add event handlers to all the buttons in the appbar.
// This function is called when the page loads.
function addAppbarNavigation() {        
  var appBar = document.getElementById('appbar');
  WinJS.UI.process(appBar);
  var appBarControl = appBar.winControl,
      commandIds = ["back", "favorite", "forward"];

  for (var i = 0; i < commandIds.length; i++) {
      var command = appBarControl.getCommandById(commandIds[i]);
      command.onclick = navigateFromAppBar;
  }
}

// Navigate to the page specified by the button.
function navigateFromAppBar(event) {
  var element = event.target;
  for (var i = 0; i < element.parentNode.childNodes.length; i++) {
    element.parentNode.childNodes[i].disabled = "";
  }
  element.parentNode.winControl.hide();
  WinJS.Navigation.navigate(element.value);
  element.disabled = 'disabled';
}

Now, with jQuery, we can create the same behavior, but with significantly less code.

// Add event handlers to all the buttons in the appbar.
// This function is called when the page loads.
function addAppbarNavigation() {
  $('#appbar button').click(navigateFromAppBar);
}

// Navigate to the page specified by the button.
function navigateFromAppBar(event) {
  var element = event.target;
  $('#' + element.parentNode.id + ' button').removeAttr('disabled');
  element.parentNode.winControl.hide();
  WinJS.Navigation.navigate(element.value);
  element.disabled = 'disabled';
}

Building on top of a ListView control

jQuery can also be a big help when used along with a WinJS.UI.ListView control. Imagine that your app displays data about a group of items for sale, where each item has an image and some info associated with it.

var items = [
  {
    name: 'item1', 
    description: 'item1 description', 
    itemPrice: 1.99,
    quantity: 20,
    pictureSRC: '/images/item1.jpg'
  },
  {
    /* Next item details. */
  }
];

Given the format of our data, we can define a template to display the array of items.

<div id="smallListTextTemplate" 
data-win-control="WinJS.Binding.Template" >
<div>
<h2 data-win-bind="innerText: name"></h2>
<img src="#" data-win-bind="src: pictureSRC" />
</div>
</div>
<div id="item-view">
  Loading items …
</div>

We can then create a WinJS.UI.ListView control that is bound to our data source when the page loads using the following code:

// Populate the 'item-view' as a ListView control with data from
// the 'items' array. This function is called when the page loads.
function createItemList(page) {

  var currentItems = new WinJS.Binding.List(items),
      listDiv = $('#item-view')[0];

  var listView = new WinJS.UI.ListView(listDiv, {
    itemDataSource: currentItems.dataSource,
    itemTemplate: smallListTextTemplate,
    oniteminvoked: getItem,
    selectionMode: 'single',
    tapBehavior: 'directSelect',
    swipeBehavior: 'none',
    layout: {type: WinJS.UI.GridLayout }
  });

  WinJS.UI.processAll(page);
}

So far, our app populates the ListView with the name and picture of each item in the items list when the page loads. But what if we want to see the cost or available quantity of an item? We might create a “details view” for our app to display more info about an item. First, we define an ‘item-details’ div of our app to show additional info about the item when it is selected in the ListView.

<div id="item-details">
<h2>Item details</h2>
<div id="item-picture"></div>
<div id="item-name"></div>
<div id="item-info">
<p>Cost per unit: $<span id="item-cost"> USD</span></p>
<p>Available quantity: <span id="item-quantity"></span></p>
</div>
</div>

When the user selects an item in the ListView, we want the app to display details about the item in the Item details section. We need to get the selected item from the ListView with the following code:

// Get the data for the selected item in the list view.
function getItem(evt) {
  var index = evt.detail.itemIndex,
      data = $("#item-view")[0].winControl.itemDataSource;

  data.itemFromIndex(index).done(
    function (result) {
      showItemDetails(result.data);
  });
}

Here’s where jQuery comes in really handy. To display the data from the item in the Item details section, we only need to use the following small function:

// Display info about the item in the 'item-details' div.
function showItemDetails(item) {

  $("#item-name").html(item.name);
  $("#item-cost").html(item.itemPrice);
  $("#item-quantity").html(item.quantity);

  $("#item-details").data(item);

  var img = new Image();
  img.src = item.pictureSRC;
  $("#item-picture").html(img);

}

The item info, taken from the data source, is then displayed in the Item details section along with its picture.

In the previous code snippet, you’ll notice that the raw data about the item is stored in the ‘item-details’ div using the jQuery data function. The data function gets or sets arbitrary data in the element(s) returned by the selector function. The data is essentially hidden from the layout of the page, meaning that you can store hidden metadata without it affecting the design of the page. This can be really helpful in scenarios where you want to store a small amount of hidden data but don’t want to store it across sessions or to instantiate a ListView control to display a set of data.

Using the previous example, if we wanted our app to add the item displayed in the Item details section to a checkout cart, we wouldn’t need to access the original data source again – we would only need to access the data associated with the ‘item-details’ element.

// Add the item shown in the Item details to the checkout cart.
function addToCart() {
  var itemToAdd = $("#item-details").data();

  $("#checkout-cart").append(
    "<div><h2>" + itemToAdd.name + "</h2>" +
    "<p>Price: $" + itemToAdd.itemPrice + "</p>" +
    "</div>"
  );
}

Promises

Both jQuery and WinJS provide their own implementation of the Promises pattern. Some jQuery functions return a promise object by default (functions like animate and get – more on those later). Other functions can be wrapped in a promise by calling the promise function on the results of the function. When you do this, the promise returns immediately with a resolved promise.

// The code in the done method that follows executes immediately.
$("div").promise().done(function (result) { });

In some circumstances, you might want to chain WinJS and jQuery promises together. Luckily, the two implementations are interoperable. jQuery promises implement the same then and done methods that WinJS uses.

In this next (somewhat silly) example, I’ve mixed jQuery and WinJS promises together using both promise chaining and the WinJS.Promise.join method. This code gets data stored in the app using the jQuery get function, creates a temporary file, writes the data from the app to the file, reads the file, and then displays the data from the file on the screen.

var tempFolder = Windows.Storage.ApplicationData.current.temporaryFolder,
    promiseArray = [],
    filename = "tempfile.txt";

promiseArray.push(tempFolder.createFileAsync(filename,
  Windows.Storage.CreationCollisionOption.replaceExisting));
promiseArray.push($.get("/data/data.txt"));

WinJS.Promise.join(promiseArray).
  then(function (response) {

    var file = response[0],
        data = response[1],
        memoryStream =
          new Windows.Storage.Streams.InMemoryRandomAccessStream(),
        dataWriter =
          new Windows.Storage.Streams.DataWriter(memoryStream);

    dataWriter.writeString(data);
    var buffer = dataWriter.detachBuffer();
    dataWriter.close();

    return Windows.Storage.FileIO.writeBufferAsync(file, buffer);
  }).
  then(function () {
    return tempFolder.getFileAsync(filename);
  }).
  then(function (file) {
    return Windows.Storage.FileIO.readTextAsync(file);
  }).
  then(function (data) {
    return $("#scenario").text(data).promise();
  }).
  done(function () {
    $("#scenario").append("<br/><br/>Finished!");
  });

Use the tools best suited for the job

Although jQuery adds a powerful complement to the APIs in Windows, it’s good to keep in mind that WinJS already provides a wealth of tools you can use. The WinJS APIs are optimized for use with Windows and are designed around app-specific scenarios (whereas jQuery is platform agnostic). If you find yourself considering whether to use jQuery or WinJS for a particular task, it’s a good idea to defer to the WinJS APIs.

Here are a handful of scenarios where WinJS already supplies the best ‘tools’ for a job.

Animating elements

jQuery includes a group of functions for animating DOM content, many of which functions are based on its animate function. However, the animations in WinJS are specially designed to make efficient use of machine resources by offloading the animation workload from the CPU to the GPU (for animations that affect transform and opacity). As a result, the WinJS animations perform well and don’t block the UI thread.

WinJS includes animations that are equivalent to the animations provided by jQuery, animations that match the design and look of Windows. Take the jQuery fadeIn and fadeOut functions, which make an HTML element fade into / out of view and change the display value of the element’s style. WinJS has the WinJS.UI.Animation.fadeIn and WinJS.UI.Animation.fadeOut functions, which also smoothly fade an HTML element into and out of view, but without changing the display value.

// Animating content into view with jQuery.
$("#content").fadeIn("slow");

// Animating content into view with WinJS and jQuery.
WinJS.UI.Animation.fadeIn($("#content")[0]);

// Animating content out of view with jQuery.
$("#content").fadeOut("fast");

// Animating content out of view with WinJS and jQuery.
WinJS.UI.Animation.fadeOut($("#content")[0]);

In the above sample, note that the WinJS effects only change the opacity of the affected elements. The jQuery animations affect the opacity and the display value, which lead to a re-layout of the page.

Compare some other jQuery animations with similar animations in WinJS: