API changes for Windows 8.1 Preview(Windows Store apps using JavaScript and HTML)

[This documentation is preliminary and is subject to change.]

This document lists API deprecations, functional changes, and optimizations introduced for Windows 8.1 Preview. For other migration resources, see:

• Upgrading your app from Windows 8 to Windows 8.1 Preview–Get started with migrating your app from Windows 8 to Windows 8.1 Preview, from start to finish. Includes best practices, deprecations, and guidance on resubmitting your app to the Windows Store.
• New APIs and features for developers–Get to know Windows 8.1 Preview by looking at new APIs and features.
• Retarget your Windows 8 Store app to Windows 8.1 Preview–Step-by-step guidance on how to migrate your app from Windows 8 to Windows 8.1 Preview.
• Updated samples–Samples for Windows 8.1 Preview that demonstrate how to use new APIs and features, and how to mitigate deprecations.
• DirectX programming–New features and improvements for games and graphic apps.

Important  For more information on API changes in Windows 8.1 Preview related to programming with C#/VB/C++ and XAML, see API changes for Windows 8.1 Preview (Windows Store apps using C#/VB/C++ and XAML).

Noteworthy items

These API changes have the highest impact in app migration:

WinJS improvements and new features

We’ve made significant investments in WinJS 2.0 to reduce HTML application start up time, improve list panning performance, and reduce memory consumption. New features such as the system scheduler, the dispose pattern, and improved support for ListView cell spanning layouts make existing scenarios faster. Compiled binding templates substantially reduce the cost of rendering multiple data bound templates into controls. Developers will notice many of these benefits without changing their WinJS 1.0 code, but some improvements require changes to the WinJS API. We encourage developers to move away from deprecated APIs, to get the best performance from their app.

In addition, new features in WinJS 2.0 further improve performance, enable enhanced platform integration, and light up new user scenarios. New controls such as the NavBar and ItemContainer enable developers to build more compelling user interfaces. For simple lists, the Repeater offers faster performance. AppBar improvements allow your app bar to scale to more device and window sizes. As you migrate your app from WinJS 1.0 to WinJS 2.0, consider where you can leverage new platform features to enhance and improve your Windows 8.1 Preview app.

Application lifetime

Quick restart after closing

In Windows 8.1 Preview, if the user closes an app and then immediately restarts it, the closed app is given up to five seconds to complete its termination before it restarts. In Windows 8, the app terminates immediately upon restart.

Suspension occurs at low priority

To improve system responsiveness in Windows 8.1 Preview, apps are given lower-priority access to resources on suspension. The suspension timeout is extended by a corresponding amount so that the app has the equivalent of 5 seconds at normal priority.

WinJS.Binding.Templates

When processing templates, data binding and control instantiation occur in different orders. If you write code in a constructor for a custom control that assumes that data-binding has already occurred, the code may not execute in the same way as before. In WinJS 1.0, templates process all control instantiation and initialization before all data binding. In WinJS 2.0, the newly optimized templates enhance fluidity in control initialization and data-binding. You can use Template.disableOptimizedProcessing to revert to WinJS 1.0 functionality. However, the new template processing is a significant performance improvement.

Background tasks infrastructure

In Windows 8, the background tasks infrastructure doesn’t perform an early validation of parameters. Parameters are validated later, when the infrastructure tries to run the background task. The error surfaces only as an entry in the event log, causing poorly developed and tested apps that find their way into the Windows Store.

We’ve changed this in Windows 8.1 Preview. The background tasks infrastructure validates parameters up front and returns a failure if they are invalid. You get immediate feedback of the problem. However, pre-existing apps simply crash and the experience escalates from partially broken to fully broken. In that case, we provide an event log.

ListLayout Grouping

In Windows 8.1 Preview, WinJS 2.0's ListLayout supports grouping. This means that you can display ListLayouts in groups by using the ListView.groupDataSource property. In WinJS 1.0, the groupDataSource property was ignored. To continue to have the desired UX here are the necessary changes.

WinJS 1.0:

listView.dataSource = list.dataSource;
listView.groupDataSource = grouplist.dataSource;
if(view.snapped) {
    listView.layout = new ListLayout();
}
else {
    listView.layout = new GridLayout({groupHeaderPosition: 'top'});
}

listView.dataSource = list.dataSource;
listView.groupDataSource = grouplist.dataSource;
if(view.snapped) {
    listView.groupDataSource = null;
    listView.layout = new ListLayout();
}
else {
    listView.layout = new GridLayout({groupHeaderPosition: 'top'});
}

ListLayout margin-collapsing not supported

In Windows 8, you use:

.win-container {
    margin-top: 10px;
    margin-bottom: 10px;
}

In Windows 8.1 Preview, we remove the margin-bottom attribute:

.win-container {
    margin-top 10px;
}

ListLayout .win-container

The ListLayout padding should move from .win-container to .win-item container. This was not originally supported in Windows 8, but didn't have any negative consequence because of the display type of the layout. In Windows 8.1 Preview, it will create a gap between the item and the selection border. Move the padding to the .win-item container and adjust the margins to the correct size to mitigate this change. This pattern is present in the Visual Studio template. Split Template, the ListView in ListLayout, Visual Studio item template, and MSDN item templates are not impacted.

ListView child combinator selectors

ListView child selectors may not work correctly due to the new Document Object Model (DOM) shape. These types of selectors worked in the past because our internal tree structure was implemented this way. An example of a child selector is .win-container>.win-item. We've added a new node to our internal tree structure, so you must update your selectors to look like this: .win-container > .win-itembox > .win-item

Note  This applies only if you use this type of selector. The Visual Studio templates use descendant selectors instead.

ListView.currentItem property

The currentItem property previously returned the current item, not taking into account header items. In Windows 8.1 Preview, it returns the current item, taking into account header items as well.

ListView.groupHeaderInvoked

In Windows 8.1 Preview, the ListView supports keyboarding to the group headers in both the GridLayout, ListLayout, and CellspanningLayout.

The ListView raises the groupHeaderInvoked event to indicate that a header has been invoked. We recommend that you move the onClick handling code to the groupHeaderInvodked event so that all inputs (touch, mouse, keyboard) are handled on group headers.

ListView .win-groupheader

Move the win-groupheader margins to the win-groupleader class. Use the new .win-groupleader class to control margins. The app's margin will be noticeably different.

Migrating from IFRAME to WebView

In Windows 8.1 Preview, XAML WebView control can only receive Windows.External.Notify messages from web sites that are on the ApplicationContentURI rules and are using HTTPS. These messages are received by the app if it handles the ScriptNotify event.

IFRAME elements within Windows Store apps using JavaScript and not within WebView controls can’t navigate to HTTP web sites. An IFRAME can navigate only to packaged content or HTTPS URIs listed in the ApplicationContentURI rules. WebView can support HTTP, but not the following:

• Geoloc
• Programmatic Clipboard
• AppCache
• IndexedDB

Move from windowed WebView control to windowless

In Windows 8.1 Preview, the WebView control in Windows Store apps using XAML and Windows Store apps using JavaScript are windowless and participate in the z-order for apps. The app bar and pop-ups can appear over the top of the WebView control. Apps that used WebViewBrush to work around this limitation should remove that workaround.

This change affects Windows Store apps using XAML in Windows 8.1 Preview, and Windows Store apps using JavaScript that use the new WebView control. Windows 8 apps are unaffected, and the existing windowed mode is used.

WinJS.UI

The following JavaScript API elements are deprecated.

WebView.ScriptNotify event

In Windows 8, the WebView.AllowedScriptNotifyUris and WebView.AnyScriptNotifyUri properties cause the WebView.AllowedScriptNotifyUris and WebView.AnyScriptNotifyUri properties cause the ScriptNotify event to fire. Because these properties are deprecated in Windows 8.1 Preview, the ScriptNotify event can’t be inspected during app on-boarding and allows an app to easily put the real work of their app on the web instead of in their app package. Instead, check the package’s ApplicationContentUriRules from the manifest. During app on-boarding, the app can inspect the manifest, which can’t be modified at run time.

Window size model

We’ve added a new window size model in Windows 8.1 Preview to support richer multitasking scenarios. The concept of discrete view states is removed and the snapped state is no longer required. Instead, apps can be sized continuously to any size down to their minimum size. An app can either have a minimum width of 500px or 320px. By default, the minimum size of an app is 500px.

The Windows 8 ApplicationView.Value property and ApplicationView.TryUnsnap method are deprecated, so you will receive warnings if your app uses them. An app should register for the window resize event to know when to update the layout. However, instead of calling ApplicationView.Value to find out which view state the app is in, the app developer should apply media queries for window size directly to make layout decisions. In Windows 8.1 Preview, it is up to the app designer to decide what window size thresholds and media queries the app makes to update the app layout.

Here are some possible ways to migrate your code.

Viewing general window size:

WWA (JavaScript)

Windows 8

Copy

function onSizeChanged() {
    // Get view state
    var currentViewState = ApplicationView.value;

    if (currentViewState === ApplicationViewState.fullScreenLandscape) {
        // Full screen Landscape layout

    } else if (currentViewState === ApplicationViewState.fullScreenPortrait) {
        // Full screen Portrait layout

    } else if (currentViewState === ApplicationViewState.filled) {
         // Filled layout

    } else if (currentViewState === ApplicationViewState.snapped) {
        // Snapped layout
    } 
}

Windows 8.1 Preview

Copy

function onSizeChanged() {
    // Get window size
    var windowWidth = document.documentElement.offsetWidth;

    // App code to change layout based on window width* 

}

WWA (media queries)

Windows 8

Copy

@media (-ms-view-state: fullscreen-landscape) {
    /* CSS styles for full screen landscape */
}

@media (-ms-view-state: fullscreen-portrait) {
    /* CSS styles for full screen portrait */
}

@media (-ms-view-state: filled) {
    /* CSS styles for filled*/
}

@media (-ms-view-state: snapped) {
    /* CSS styles for snapped */
}

Windows 8.1 Preview

Copy

@media (min-width: 500px) and (max-width: 1023px) {
    /* CSS styles to change layout based on window width */
}

@media (min-width: 1024px) {
    /* CSS styles to change layout based on window width */
}

Viewing orientation:

WWA (JavaScript)

Windows 8

Copy

function onSizeChanged() {
    // Get view state
    var currentViewState = ApplicationView.value;

    if (currentViewState == ApplicationViewState.fullScreenLandscape || currentViewState == ApplicationViewState.filled) {
        // Landscape layouts

    } else if (currentViewState == ApplicationViewState.fullScreenPortrait) {
        // Portrait layouts

    }
}

Windows 8.1 Preview

Copy

function onSizeChanged() {
    // Get the window orientation
    var winOrientation = ApplicationView.getForCurrentView().orientation;

    if (winOrientation === ApplicationViewOrientation.landscape) {
       // Landscape layouts

    } else if (winOrientation === ApplicationViewOrientation.portrait) {
       // Portrait layouts

    }
}

WWA (media quieries)

Windows 8

Copy

@media (-ms-view-state: fullscreen-landscape) or (-ms-view-state: filled)  {
    /* CSS styles for landscape layouts */
}

@media (-ms-view-state: fullscreen-portrait) {
    /* CSS styles for portrait layouts */
}

Windows 8.1 Preview

Copy

@media (orientation: landscape) {
    /* CSS styles for landscape layouts */
}

@media (orientation: portrait) {
    /* CSS styles for portrait layouts */
}

Document Object Model (DOM) improvements

The Windows 8.1 Preview platform for JavaScript developers introduces several enhancements to improve performance and the compatibility of common frameworks of Web content. With these changes, developers will notice better performance of their existing code. They will be able to make fewer changes, to adapt their modern Web code to run in Windows 8.1 Preview applications.

These changes also include removing several deprecated APIs in the Windows 8.1 Preview platform for JavaScript developers, in favor of their standards-based and modern equivalents. Together, these changes help prevent common JavaScript frameworks from misidentifying the Windows 8.1 Preview platform for JavaScript developers, as an earlier version of Internet Explorer.

Deprecated DOM APIs

The following JavaScript API elements are deprecated. For functional changes, use a web-platform based equivalent. For legacy data-binding changes, use data binding from JavaScript frameworks such as the Windows Library for JavaScript (WinJS).

These navigator object members are not deprecated, but have altered return values:

• userAgent
• appVersion
• appName
• product

Fonts for existing scripts

We are updating the Document Object Model (DOM) default fonts and UI fonts for Windows Store app using JavaScript for several languages, as defined in the table below. This means that certain webpages and web apps that depended on Internet Explorer’s old default fonts may look different. Although their overall appearance should be improved, this change could confuse certain tests that depend on a specific look for certain scripts. For example, Arabic with no font specification now defaults to Times New Roman as opposed to Simplified Arabic. The UI font is determined on a per-language basis. For example, for Windows Store apps using JavaScript, UI fonts for Japanese will now be Meiryo UI. You can mitigate the effect of this change by specifying a particular font instead of relying on old default fonts, and by updating your tests to expect the new font values.

Disable pseudo hit testing in IE 11 Mode

We are disabling legacy Internet Explorer functionality that allowed clicks and other touch or mouse interaction to conditionally pass through transparent backgrounds, known as “pseudo hit testing.” This functionality was often seen as inconsistent because it varied based on the content behind the transparent layer and was not used for direct manipulation like pan and zoom. This change helps to raise the default compatibility of Internet Explorer's latest mode for public web sites while improving cross-browser interoperability. In Windows 8, this functionality prevented items on some sites from being activated in response to a click because the event would "pass through" a transparent layer and fire on the wrong element.

Affected content will appear not to respond to user interaction and can be seen as being obscured by another layer when using the Select element by click feature in F12 tools or Microsoft Visual Studio. Changing the z-index or the bounds of the transparent layer, to avoid obscuring the affected content, usually resolves the issue.

The Windows Library for JavaScript (WinJS) depended on this functionality when drawing the keyboard focus rectangle for an item in the ListView control. If you've embedded an older copy of WinJS in your app, upgrade to the current version when migrating your app from Windows 8 to Windows 8.1 Preview.

Load dynamically added scripts asynchronously in Windows Store apps using JavaScript

Dynamically added script elements will now load asynchronously for protocols for Windows Store apps using JavaScript (ms-appx*), to align with the functionality of web protocols (http*). Previously such scripts could load synchronously and block the UI depending on the order in which their attributes were set.

Windows Store apps written for Windows 8.1 Preview load scripts dynamically and attempt to use functions from the script immediately. Update affected content to do one of these:

• Load scripts statically in the HTML markup of the page.
• Set "script.async=false" on dynamically loaded scripts, to ensure that they execute in the order in which they are added.
• Wait for the "load" event of a script element to fire before using functions defined in the script.

We have updated the WinJS fragment loader to be compatible with this change. When you migrate your apps to Windows 8.1 Preview, make sure that you have the latest version of WinJS to avoid issues.

Related topics

Upgrading your app from Windows 8 to Windows 8.1 Preview

New APIs and features for developers

Retarget your Windows 8 Store app to Windows 8.1 Preview

Updated samples

DirectX programming

API changes for Windows 8.1 Preview (Windows Store apps using C#/VB/C++ and XAML)

Build date: 7/1/2013