Quickstart: Adding Page controls (HTML)

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 create and display PageControl objects.

Prerequisites

We assume that you can create a basic Windows app using JavaScript that uses Windows Library for JavaScript controls. For instructions on getting started with WinJS controls, see the Quickstart: adding WinJS controls and styles.

To create a PageControl

Unlike other Windows Library for JavaScript controls, you don't instantiate a PageControl directly. Instead, you create a PageControl by calling the WinJS.UI.Pages.define method and passing it the Uniform Resource Identifier (URI) of the HTML file that defines the PageControl and an object that defines the PageControl members.

Here's a an example of a PageControl definition. It's made up of three files: an HTML file, a CSS file, and a JavaScript file.


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

    <!-- WinJS references -->
    <link href="/pages/samplePageControl.css" rel="stylesheet">
    <script src="/pages/samplePageControl.js"></script>
</head>
<body>
    <div class="samplePageControl">
        <p class="samplePageControl-text"><span data-win-bind="textContent: controlText">Message goes here</span>
        <button class="samplePageControl-button">Click me</button></p>
        <p>Page controls can also contain WinJS controls. They are activated automatically.</p>
        <div class="samplePageControl-toggle" data-win-control="WinJS.UI.ToggleSwitch"></div>
    </div>
</body>
</html>


/* samplePageControl.css */
.samplePageControl
{
    padding: 5px;
    border: 4px dashed #999999;
}


// samplePageControl.js
(function () {
    "use strict";

    var ControlConstructor = WinJS.UI.Pages.define("/pages/samplePageControl.html", {
        // This function is called after the page control contents
        // have been loaded, controls have been activated, and
        // the resulting elements have been parented to the DOM.
        ready: function (element, options) {
            options = options || {};
            this._data = WinJS.Binding.as({ controlText: options.controlText, message: options.message });

            // Data bind to the child tree to set the control text
            WinJS.Binding.processAll(element, this._data);

            // Hook up the click handler on our button
            WinJS.Utilities.query("button", element).listen("click",
                // JavaScript gotcha - use function.bind to make sure the this reference
                // inside the event callback points to the control object, not to
                // window
                this._onclick.bind(this));

            // WinJS controls can be manipulated via code in the page control too
            WinJS.Utilities.query(".samplePageControl-toggle", element).listen("change",
                this._ontoggle.bind(this));
        },

        // Getter/setter for the controlText property.
        controlText: {
            get: function () { return this._data.controlText; },
            set: function (value) { this._data.controlText = value; }
        },

        // Event handler that was wired up in the ready method
        _onclick: function (evt) {
            WinJS.log && WinJS.log(this._data.message + " button was clicked", "sample", "status");
        },

        // Event handler for when the toggle control switches
        _ontoggle: function (evt) {
            var toggleControl = evt.target.winControl;
            WinJS.log && WinJS.log(this._data.message + " toggle is now " + toggleControl.checked, "sample", "status");
        }
    });

    // The following lines expose this control constructor as a global.
    // This lets you use the control as a declarative control inside the
    // data-win-control attribute.

    WinJS.Namespace.define("Controls_PageControls", {
        SamplePageControl: ControlConstructor
    });
})();

To create a Page control in Microsoft Visual Studio, select Project > Add New Item from the main menu, then select Page Control.

Displaying a PageControl

Once you've defined your PageControl, there are a few ways you can display it:

Use the WinJS.UI.Pages.render function.

<div class="renderingPageControls-renderedControl"></div>

// Render the page control via a call to WinJS.UI.Pages.render. This lets
// you render a page control by referencing it via a url.
var renderHost = element.querySelector(".renderingPageControls-renderedControl");
WinJS.UI.Pages.render("/pages/SamplePageControl.html", renderHost, {
    controlText: "This control created by calling WinJS.UI.Pages.render",
    message: "Render control"
}).done();

Publicly expose the PageControl object's constructor and use it to create the PageControl.

<div class="renderingPageControls-createdProgrammatically"></div>

// Render the page control by creating the control.
var constructedHost = element.querySelector(".renderingPageControls-createdProgrammatically");
new Controls_PageControls.SamplePageControl(constructedHost, {
    controlText: "This control created by calling the constructor directly",
    message: "Constructed control"
});

Use the WinJS.UI.Pages.get function to get a constructor for the PageControl.
Instantiate the control in HTML as if it were a Windows Library for JavaScript control (which it is). You must publicly expose the PageControl object's constructor for this to work.
```
<div data-win-control="Controls_PageControls.SamplePageControl"
    data-win-options="{controlText: 'This was created declaratively', message: 'Declarative control' }">
</div>
```

Use an HtmlControl to render the page.

 <div class="renderingPageControls-htmlControl" data-win-control="WinJS.UI.HtmlControl"
    data-win-options="{uri: '/pages/samplePageControl.html',
    controlText: 'This was rendered via the HtmlControl', 
    message: 'HTML Control loaded control' }"></div>

Summary and next steps

You learned how to create and display PageControl objects.

For more info about how to use PageControl objects, see Quickstart: Using single-page navigation.

Quickstart: Adding Page controls (HTML)

Prerequisites

To create a PageControl

Displaying a PageControl

Summary and next steps

Additional resources