IPageControlMembers.ready method

Called after init and render are complete. At this time, the element is ready for use.


WinJS.UI.Pages.define("yourPage.html", {
    ready: function (element, options) { /* your code here */ },
    // Other methods of PageControl


  • element
    Type: DOMElement

    The DOM element that contains all the content for the page.

  • options
    Type: Object

    An object that contains one or more property/value pairs to apply to the PageControl. How these property/value pairs are used (or not used) depends on the implementation of that particular PageControl.

Return value

Type: Promise**

If asynchronous processing is necessary, a promise that is fulfilled when the element is ready for use. Otherwise, nothing.


This example defines a PageControl that implements the ready method.

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

    <!-- WinJS references -->
    <link href="/pages/samplePageControl.css" rel="stylesheet">
    <script src="/pages/samplePageControl.js"></script>
    <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>
// 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

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

        // 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

The next example renders the PageControl in another HTML file.

<h2>This control is rendered declaratively, as if it were a control. Which it is!</h2>
<div class="renderingPageControls-declarativeControl" data-win-control="Controls_PageControls.SamplePageControl"
    data-win-options="{controlText: 'This was created declaratively', message: 'Declarative control' }"></div>

For the full code, see the HTML Page controls sample (Windows).


Minimum WinJS version

WinJS 1.0



See also

For developers


Your first app - Part 3: PageControl objects and navigation

Navigating between pages

Quickstart: Using single-page navigation

Quickstart: Adding Page controls

Adding a Page control item template

HTML Page controls sample

Navigation and navigation history sample

For designers

Navigation patterns