IPageControlMembers.render method

Article
01/26/2017

Takes the elements returned by the load method and attaches them to the specified element.

In general, you don't need to override this method. The Windows Library for JavaScript provides a default implementation of this method that works for most PageControl scenarios.

Syntax

iPageControlMembers.render(element, options, loadResult);

Parameters

element
Type: DOMElement

The DOM element to which the loadResult elements are appended.
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.
loadResult
Type: Promise**

A Promise that contains the elements returned from the load method.

Return value

This method does not return a value.

Examples

This example defines a PageControl that overrides the render 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