IPageControlMembers.load method

Article
01/26/2017

Creates Document Object Model (DOM) objects from the content in the specified Uniform Resource Identifier (URI).

This method is called after the PageControl is defined and before the init method is called.

Syntax

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

Parameters

uri
Type: String

The URI from which to create DOM objects.

Return value

Type: Promise**

A promise whose fulfilled value is the set of unparented DOM objects.

Remarks

The Windows Library for JavaScript provides a default implementation of this method that uses the WinJS.UI.Fragments API to copy DOM objects from the specified URI.

Overriding the load method

Override this method if you want to generate your content using a different mechanism than just copying the DOM elements from the specified URI. For example, you could override this method to generate a content template or to extract only certain data from the specified URI.

For this override to be used, the PageControl that contains the load override needs to be defined by calling WinJS.UI.Pages.define before calling WinJS.UI.Pages.render.

Examples

This example defines a PageControl that overrides the default load method.

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

    <script src="/pages/advancedControl.js"></script>
</head>
<body>
    <div class="advancedControl fragment">
        <p>This content actually gets ignored, since the page control
            has overridden the load and render methods.
        </p>
    </div>
</body>
</html>

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

    WinJS.UI.Pages.define("/pages/advancedControl.html", {

        // The load method is called to actually retrieve the information from
        // the uri provided. The default implementation calls the low level
        // fragment loader to retrieve the content. By overriding this, you are
        // taking control of the loading process.
        //
        // For the purposes of this sample, instead of using any external content,
        // we'll just supply some raw HTML.
        //
        // Expected uses of this overload would be if you were generating your
        // content via some other mechanism like a JavaScript templating library.
        load: function (uri) {
            this._log = ["load called"];

            // As the API is defined, you are required to return a promise for the content.
            // This makes sense, as downloading content from the web or disk is an async
            // operation. Since in this case we're returning static data, we return
            // a promise for our static data via WinJS.Promise.as
            return WinJS.Promise.as({ preamble: "<p>", postamble: "</p>" });
        },

        // The next method called in the page lifecycle is init.
        // At this point, external assets are not available yet.
        // This method is a good place to kick off async processes
        // that may take a while.
        //
        // init can return a promise that completes when init is finished.
        // In this case we aren't doing any init work that we want to delay
        // so this method doesn't return anything.
        init: function (element, options) {
            // Fake out something async, we'll finish this off in the
            // processed callback.
            this._asyncActivity = WinJS.Promise.timeout(1500);

            // Add a log entry - these will get rendered in the render method.
            this._log.push("init called");
        },

        // The render function is called after load and init
        // completes. It receives the result from the load promise, and then is
        // responsible for actually parenting it into the DOM.
        //
        // In this case, we'll just set the content manually.
        render: function (element, options, loadResult) {
            this._log.push("render called");

            // Render our contents
            var content = [];
            this._log.forEach(function (item) {
                content.push(loadResult.preamble + item + loadResult.postamble);
            });

            WinJS.Utilities.setInnerHTML(element, content.join(""));
        },

        // The processed method is called after render is complete and
        // the system has called WinJS.UI.processAll on the content.
        // It's a useful place to wait for async activity to finish as
        // well.
        //
        // You can return a promise here, that will delay the rest of the
        // process until the promise completes.
        processed: function (element, options) {
            return this._asyncActivity.then(function () {
                var p = document.createElement("p");
                p.textContent = "processed called";
                element.appendChild(p);
            });
        },

        // The ready method is called after everything has finished being adding to the DOM
        // and controls are processed. In most cases, this is the only method you'll need
        // to implement.
        ready: function (element, options) {
            var p = document.createElement("p");
            p.textContent = "This control was created";
            element.appendChild(p);
            WinJS.log && WinJS.log("Control creation complete", "sample", "status");
        },

        // This function is NOT part of the creation lifecycle. However, it demonstrates that
        // you can define arbitrary additional functions on page controls. In this case, it's
        // used by the hosting code.
        unloadExample: function () {
            WinJS.log && WinJS.log("Control has been unloaded", "sample", "status");
        }
    });
})();

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

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI.Pages