WinJS.UI.Animation.enterPage function

Article
01/26/2017

Performs an animation that shows a new page of content, either when transitioning between pages in a running app or when displaying the first content in a newly launched app.

The following video demonstrates this animation:

Syntax

WinJS.UI.Animation.enterPage(element, offset).done( /* Your success and error handlers */ );

Parameters

element
Type: Object

Element or an array of elements that represent the content. If element refers to an array of elements, the elements enter in array order.
offset
Type: Object

An initial offset where the element or elements begin relative to their final position at the end of the animation. Set this parameter to null to use the recommended default offset.

Note When the element parameter specifies an array of elements, the offset parameter can specify an offset array with each item specified for its corresponding element array item. If the array of offsets is smaller than the array of elements, the last offset is applied to all remaining elements.

Return value

Type: Promise**

An object that completes when the animation is finished.

Remarks

See the HTML animation library sample on the Windows Dev Center for a usage example of this function.

The element parameter can be expressed in several ways:

As the special value "undefined", which means that the animation has no such target
As a single object
As a JavaScript array (possibly empty), in which each element of the array can be a single element or a JavaScript array of elements.
As a NodeList (for example, the result of querySelectorAll)
As an HTMLCollection

The offset parameter can also be provided in several forms:

As the special value "undefined", which can be specified explicitly in the call or specified implicitly by omitting the parameter value. The undefined value means that the animation's default offset will be used. This is the equivalent of setting the offset parameter to null.
As a single JavaScript object of this form:

{ top: string, left: string, rtlflip: true | false }

For example:

{ top: "12px", left: "0px", rtlflip: true }

The object must have properties named top and left that represent the offset applied at the beginning of the animation. Any valid CSS units can be used to express the offset. In this form, the offset applies to all elements involved in the animation.

The rtlflip parameter flips the values to a right-to-left alignment. It affects the left parameter and changes its sign. For instance, 10 px becomes -10px. This parameter is optional and can be omitted. If it is omitted, the default value is false.
As a JavaScript array (possibly empty) of the {top: ..., left: ..., rtlflip: ...} objects discussed above. In this case, each object in the array applies to a single element in the animation, in the order given; the first object applies to the first element, the second to the second, and so on. If the number of elements is greater than the number of objects in this array, then the last element in the array applies to all of the remaining elements.

Examples

The following examples, adapted from the HTML animation library sample, show this function in use. These examples uses the elements found in the default.html page used in the sample:

<body role="application">
    <div id="rootGrid">
        <div id="header" role="contentinfo" data-win-control="WinJS.UI.HtmlControl" data-win-options="{uri: '/sample-utils/header.html'}"></div>
        <div id="content">
            <h1 id="featureLabel"></h1>
            <div id="contentHost"></div>
        </div>
        <div id="footer" data-win-control="WinJS.UI.HtmlControl" data-win-options="{uri: '/sample-utils/footer.html'}"></div>
    </div>
</body>

Note All of the following examples use the default offset (offset = null). We recommend that you always use default offset values unless you have a truly exceptional situation, due to these benefits:

Better animation performance
Automatic mirroring in right-to-left apps
Designer-recommended translation distance, automatically adjusted (in applicable animations) when your app is resized to a narrow width

The call to the enterPage function shown here brings the entire page in at once. The Promise object returned by the call is assigned to an enterPage variable.

enterPage = WinJS.UI.Animation.enterPage(rootGrid, null);

You can also bring in a page in sections with staggered timing as shown in the next examples. For best practices around splitting your content in this way, see Guidelines and checklist for page transition animations.

This variation of the call staggers the entry of the header and body sections of the page. Note that in this call, the element value is provided by a two element array, each of which specifies the ID of two different pieces of the page. The staggering of the entry of the elements only applies to the top level of the array, so in this case header and featureLabel enter together, followed by contentHost and footer entering together.

enterPage = WinJS.UI.Animation.enterPage([[header, featureLabel], [contentHost, footer]], null);

If you wanted each of the elements in the previous call to enter sequentially, the call would look like this:

enterPage = WinJS.UI.Animation.enterPage([header, featureLabel, contentHost, footer], null);

This variation of the call staggers the entry of three different areas of the page. Note that in this example, elements defined in three different sources in the sample project (default.html, enterPage.html, and sample-utils.css) are mixed together, showing that you bring disparate elements in together.

enterPage = WinJS.UI.Animation.enterPage([[header, featureLabel], [inputLabel, input], [outputLabel, output, footer]], null);

Finally, you can use the Promise object's done method to do any necessary clean-up once the animation is complete.

enterPage.done(
    function () {
        content.style.overflow = "auto";
    });

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI.Animation