Basics: Introduction

All WinJS controls follow the same conventions. When creating a WinJS control, the common approach is to declare it directly in the HTML. The control is declared within an element like <div>, with two custom attributes: data-win-control and data-win-options.

  • The first attribute, data-win-control is required and specifies the constructor of the control; it will always take the form WinJS.UI.<NameOfControl>.
  • The second, data-win-options takes an object containing key-value pairs separated by commas: { <key1>: <value1>, <key2>: <value2>, ... }. Each key represents a property of the control that can be customized. You can even specify event handlers in data-win-options by prefixing the event name with 'on', like the example below.
  • data-win-options="{ label: 'Home', icon: 'home',
                        onclick: /*do something */}"

The data-win-* parameters become the constructor options that are used to initialize the control and tells WinJS where to create the control in the HTML. A declaration typically looks like this:

<div id="myControl" data-win-control="WinJS.UI.Rating" data-win-options="{
    averageRating: 3.4,
    maxRating: 10,
    onchange: basics.changeRating }">

With this syntax, WinJS.UI.processAll() must be called in your JavaScript file to process the data-win-* attributes, as they will otherwise be ignored when rendering.

WinJS.UI.processAll() runs the constructor specified in data-win-control (WinJS.UI.Rating in the example) with the attributes in data-win-options and creates the actual control in the DOM, attaching it to the element it was created in, here the div with id="myControl". You can access the WinJS control by using the winControl property:

var myRatingControl = document.getElementById("myControl").winControl;

The winControl gives you access to all the data and functionalities of the WinJS control. Basically, any property you can set in the data-win-options, you can also access through winControl after the WinJS control has been rendered:

var avgRating = document.getElementById("myControl").winControl.averageRating;

Note: It is important to know that winControl can be accessed only after WinJS.UI.processAll(), has completed its processing, as the WinJS controls do not exist until WinJS.UI.processAll() creates them.

Try It Out

Check It Out

In this tutorial, we will build a simple application called TrailRater that lets the user rate hiking trails. Fill in the missing pieces in the HTML code below to create a WinJS control called a SplitView.

In the HTML:

  1. Tell the div that you would like it to be a SplitView by setting data-win-control as the SplitView constructor. The SplitView constructor is WinJS.UI.SplitView
    <div class="splitView" data-win-control="WinJS.UI.SplitView">
  2. The SplitView also comes with a side bar for navigation. This side bar will allow the user to click on a trail in the side menu, in order to go to the page describing the trail. Let's create one of these navigation icons. The constructor is WinJS.UI.SplitViewCommand.
    <div class="nav-commands">
      <div data-win-control="WinJS.UI.SplitView"></div>
  3. This button will have three customizable features: a label, an icon type and an onclick event handler that updates the UI to show the trail page. We want the label to say 'Alki Trail' and the icon shown to be the 'mappin' icon.
  4. <div class="nav-commands">
      <div data-win-control="WinJS.UI.SplitViewCommand" data-win-options= "{
          label:'Alki Trial',
          icon:'mappin', }">

Check the output when you're done to see how it looks!

Clicking "Yes" will replace the code in the editor with the correct code.
Are you sure you want to do this?