How to set event handlers declaratively

Article
08/10/2016

[ 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 set event handlers declaratively (in your HTML markup) for HTML and Windows Library for JavaScript controls.

What you need to know

Technologies

Prerequisites

We assume that you can create a basic Windows app using JavaScript that uses WinJS controls. For instructions about how to get started with WinJS controls, see the Quickstart: adding WinJS controls and styles.

Instructions

Set an event handler on an HTML control declaratively

This example shows you how to create an onclick event handler for a button. When you click the button, the handler updates an output div element with the click coordinates. Here's the HTML markup that we start with.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>CodingBasicApps</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <!-- CodingBasicApps references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body>
    
    <button id="button1" onclick="startPage.clickEventHandler(event)">An HTML button</button>
    <div id="button1Output">&nbsp;</div>
</body>
</html>

In your JavaScript file, create your event handler. This example creates handles for the onclick event of a button.

// The click event handler for button1
function button1Click(mouseEvent) {
    var button1Output = document.getElementById("button1Output");
    button1Output.innerText =
        mouseEvent.type
        + ": (" + mouseEvent.clientX + "," + mouseEvent.clientY + ")";

}

As described in Coding basic apps, if you're following good programming practices, everything in your JavaScript file will be private. Before you can set the button control's onclick event in your HTML, you must make it public. One way to do this is to define a namespace and add your event handler as a public member.
```
WinJS.Namespace.define("startPage", { clickEventHandler: button1Click });
```
In your HTML file, set control's event handler to namespace.member(event). This example sets onclick to startPage.clickEventHandler(event).
```
<button id="button1" onclick="startPage.clickEventHandler(event)">An HTML button</button>
<div id="button1Output"></div>
```

Set an event handler on a Windows Library for JavaScript control declaratively

This example shows you how to set the onchange event of a WinJS.UI.Rating control. When you select a rating, the handler updates an output div element with the new rating value. Here's the HTML markup that we start with.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>DeclaringWinJSEventsInMarkup</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <!-- DeclaringWinJSEventsInMarkup references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body>
    <div style="margin:50px">
        <div id="ratingControlHost" 
            data-win-control="WinJS.UI.Rating">
        </div>
        <div id="ratingOutputDiv">&nbsp;</div>
    </div>
</body>
</html>

In your JavaScript file, create your event handler. This example creates a handler for the onchange event of a Rating.

function ratingChanged(eventInfo) {
    var ratingOutputDiv = document.getElementById("ratingOutputDiv");
    ratingOutputDiv.innerText = eventInfo.detail.tentativeRating;
}

Here's where there's a difference between setting an event handler for an HTML control and setting one for a WinJS control.

To protect your app, WinJS controls can't declaratively access your functions, even if they're public. You can grant the WinJS access to your function by calling the WinJS.UI.eventHandler method and passing it your event handler.
```
WinJS.UI.eventHandler(ratingChanged);
```
WinJS.UI.eventHandler adds a property to your function named supportedForProcessing and sets it to "true". If you want to make a function other than an event handler accessible to the WinJS through HTML, you can use WinJS.Utilities.markSupportedForProcessing. You can also just add the supportedForProcessing property to your function manually; the WinJS.UI.eventHandler and WinJS.Utilities.markSupportedForProcessing functions are just provided for convenience.

Make your event handler public by exposing it through a namespace.

WinJS.Namespace.define("startPage", {
    ratingChangedHandler: ratingChanged
});

In your HTML file, set control's event handler to namespace.member. This example sets onchange to startPage.ratingChangedHandler.

<div id="ratingControlHost" 
    data-win-control="WinJS.UI.Rating" 
    data-win-options="{onchange: startPage.ratingChangedHandler}">
</div>
<div id="ratingOutputDiv">&nbsp;</div>

Remarks

For more info about why you must expose event handlers publicly and for other ways to register event handlers, see Coding basic apps.

Adding and styling controls

Coding basic apps