The x-ms-webview is a powerful control that lets you embed web content directly in your app’s UX. This control has been available to XAML Windows Store apps since Windows 8, and in Windows 8.1 we’ve made lots of great updates, which are described in Sam Spencer’s blog post, What’s new in WebView in Windows 8.1. As noted in Sam’s post, one of the biggest updates is that the control is now available for apps written in HTML and JavaScript!

If you’re an HTML/JS app developer, the x-ms-webview offers you a great way to add web content to your app’s experience. In this post we’ll dive into why you’ll want to upgrade your app to use x-ms-webview. I’ll also give some tips on how to take advantage of all the x-ms-webview has to offer.

Why did we build an HTML x-ms-webview?

When I talk to HTML developers about the new x-ms-webview control the most common initial reaction I hear is, “Why would I need that?” Because apps written in JavaScript already have the ability to host web content in an iframe element, it’s a great question. But iframes have several limitations that make embedding web content cumbersome, or even impossible, in certain situations. For example:

  • Framebusting sites – A lot of major web properties detect if they are being hosted in an iframe and simply don’t render. The x-ms-webview acts like a browser when communicating with the underlying content.
  • Document loading events – For iframes, detecting when content was loaded was either a waiting game or an art form. By trying to use postMessage() to detect when content the DOM content is loaded, the x-ms-webview exposes a rich set of events to make this deterministic for app development.

The x-ms-webview solves all these problems. Additionally the x-ms-webview provides new functionality that was never possible with an iframe:

  • Better access to local content – Access to local state folder content to load into x-ms-webview. This provides ebook readers with a means to render books that are stored locally.
  • Screenshots of web content – The ability to take a screenshot of the x-ms-webview content to make it easy provide content to the Share contract.

So to answer the original question, of why an HTML and JavaScript app needs a webview… All these features mean the x-ms-webview is simply the best way for your app to display web content.

What does the x-ms-webview look like?

Just to cover the basics, the Webview is an HTML element that’s part of the DOM for JavaScript apps. We use x-ms- appended to the x-ms-webview element name to denote this is a vendor specific HTML feature (e.g. “x-vendor-feature”). Using this element should seem familiar as the syntax is similar to an iframe.

HTML element

JavaScript

Adding a basic x-ms-webview control to the default.html page in a Windows Store app written in JavaScript looks like this:

HTML

<!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–> <!–CRLF–></script>

</head>

<body>

<x-ms-webview id=”webview” src=”http://www.bing.com” width=”500px” height=”500px”></x-ms-webview>

</body>

</html>

When simply adding a x-ms-webview control, the default size is 100px by 100px. You can specify the width and height just like an iframe, or you can use CSS styles for the iframe.

Navigation with x-ms-webview

Now that you have a sense for the x-ms-webview control and how it loads content, understanding the navigation workflow helps you control when things happen. One common problem for Windows 8 developers, when incorporating web content in their apps, was detecting when the entire DOM was loaded in order to start manipulating DOM objects or executing JavaScript. x-ms-webview supports the navigation flow events, as well as the navigation history, in order to give you control over web content loading in your app.

Navigation history properties and methods

Navigation history properties and methods

API for handling x-ms-webview navigation

navigate() – When you call this API you can also subscribe to these events that are raised during a Navigation request:

DOM event name

Description

MSWebViewNavigationStarting

Indicates the WebView is starting to navigate

MSWebViewContentLoading

The HTML content is downloaded and is being loaded into the control

MSWebViewDOMContentLoaded

Indicates that the main DOM elements have finished loading

MSWebViewNavigationCompleted

Indicates the navigation is complete, and all media elements are rendered

MSWebViewUnviewableContentIdentified

The WebView found the content was not HTML

In addition to these events in case the site being loaded has iframes there is another set of events exposed for you to detect sub content loading via iframes:

DOM event name

Description

MSWebViewFrameNavigationStarting

Indicates an iframe within a WebView is starting to navigate

MSWebViewFrameContentLoading

The HTML content is downloaded and is being loaded into the control iframe

MSWebViewFrameDOMContentLoaded

Indicates that the main DOM elements have finished loading in the iframe

MSWebViewFrameNavigationCompleted

Indicates the navigation is complete, and all media elements are rendered in the iframe

x-ms-webview navigation history. Detecting if a user has navigated inside the x-ms-webview is simple with these properties and methods.

Properties:

  • canGoBack – returns true/false if the control can navigate back.
  • canGoForward – returns true/false if the control can navigate forward.

Methods:

  • goBack() – Navigates the control to the previous location.
  • goForward() – Navigates the control to the next location.

JavaScript navigation history

HTML

CSS

JavaScript

Content sources

Now that we know the WebView is a straightforward HTML element, let’s look at the types of content you can load into a x-ms-webview and the different methods available for each.

Graphic showing the methods designed for internet and local content navigation

Graphic showing the methods designed for internet and local content navigation

Internet content

Integrating online content from the internet is the most common way to use an x-ms-webview. For example, one of the demo apps we built for Build 2013 showed a local product catalog, that used an x-ms-webview to handle the customer checkout with an existing website. For more details, see John Hazen’s Build talk, WebView: Bringing the Web to Your App.

One way to load web content in an x-ms-webview is to set the src attribute on the HTML element. Setting the src attribute automatically calls the navigate() method and passes in the attributes URI string.

Another way to load web content is to call navigate() directly. The x-ms-webview control navigates and loads websites, even ones that traditionally wouldn’t be loaded by an iframe due to framebusting.

NOTE: If the src attribute of the HTML element is set, and a call is made to the navigate method on load of an app, double navigation occurs.

Navigation supports different protocols to access both web and local content. JavaScript examples are provided for each protocol.

This table contains the different URI schemas supported by x-ms-webview. See MSDN for more details about these URI schemas.

URI schema

Description

http://

Arbitrary web content

https://

Web content over secure socket layer

ms-appdata:///

Content placed in the app’s local state folder

ms-appx-web:///

Content a developer has included within their app package but should be treated as web content. This HTML cannot access Windows RT APIs

ms-local-stream://

Content a developer has loaded into a memory stream

JavaScript navigation to web content

navigateWithHttpRequestMessage() – The control supports adding HTTP request information before navigating. This allows the server to potentially take action on the request before returning content.

JavaScript – Get example

JavaScript – Post example

Local content

You can also point an x-ms-webview at locally stored content that was either included in your package, or downloaded into a local state folder. Creating offline experiences for apps helps to ensure no matter what a person’s connected state is, you’re still able to provide an optimal app experience. A common scenario for this is to enable a game to run when not connected to the network.

In other cases your app might need better performance for loading and rendering content that can only be achieved through local content. A common scenario for this pattern is creating an electronic publication (EPUB) reader. EPUB 3 formats support rich HTML 5, CSS, and JavaScript content, which is easily displayed in the x-ms-webview control. Let’s look at the APIs you can use to load local content into the x-ms-webview.

JavaScript – Navigating to local content

JavaScript – Navigating to local content

While the simple example above works, you can use this example to create a simple HTML file in your local state directory.

navigateToLocalStreamUri() – This method provides the ability to intercept content before it’s loaded into the control. A common scenario is to decode local content before the output is sent to the x-ms-webview. An IUriToStreamResolver must be written in either C#/VB, or C++, so JavaScript developers need to include an extra project type in order to utilize this functionality. The SDK has an example of this baked in.

Example – Calling a navigateToLocalStreamUri from JavaScript, relies on underlying C# code to perform the stream resolution. For the complete example, look at the SDK.

JavaScript – Navigating to a stream

navigateToString() – Constructing and rendering dynamic HTML is common for apps that want to use HTML layout for a small amount of content, either for a quick overlay of content, or a rich in-app ad experience.

JavaScript – Navigating to string HTML content

App to WebView communication

It’s very common that your app will need to communicate with the web content within your x-ms-webview to create the appropriate user experience. You can communicate between the app and the website by integrating your app with Windows features like AppBar, Search charm, or Share charm to send messages between the two.

The invokeScriptAsync method is similar to using a postMessage() call into an <iframe> element.

The app is always allowed to use the controls invokeScriptAsync method call to execute script inside the embedded content. However, the embedded content has some restrictions when trying to send messages via the MSWebViewScriptNotify event to the parent app container.

Host app to webcontent communication graphic

Host app to webcontent communication graphic

This table shows when the webview control allows messages to flow to the parent app.

URI schema

MSWebViewScriptNotify

http://

No

https://

Yes*

ms-appdata:///

No**

ms-appx-web:///

Yes

ms-local-stream://

Yes

*Only if ContentURIs are declared in the Package.appxmanifest

**Can use a UriResolver to have ScriptNotify enabled

DOM event name

Description

MSWebViewScriptNotify

This event fires when a page inside the webview calls the window.external.notify method.

JavaScript

JavaScript

Interacting with x-ms-webview content
Graphic showing the capturePreviewToBlogAsync method call to output image format

Graphic showing the capturePreviewToBlogAsync method call to output image format.

You can now get a screenshot of the content within an x-ms-webview built into the API. <iframe> can’t render arbitrary HTML into a bitmap. However, the x-ms-webview capturePreviewToBlobAsync() method allows for producing an image.

JavaScript

Graphic showing Selected HTML (text+image) to output in the host application

Graphic showing Selected HTML (text+image) to output in the host application.

You are able to easily share content from an x-ms-webview control via the Windows Share contract. A built in API can extract content selected by a user. This content can then be returned to your app for sharing with other apps that support the share target contract.

JavaScript – Get user selected content

Want to learn more?

As you can see, the x-ms-webview is a powerful tool for displaying web content in your HTML and JS apps. If you already have a Windows 8 app that uses iframes to embed web content, I highly recommend updating to the x-ms-webview in Windows 8.1. And if you’re starting a new app, definitely use the x-ms-webview control from the beginning.

If you’re interested in learning more about x-ms-webview, check out these great links

Code samples

Build talk

Other blogs

-Kevin Hill, Senior Program Manager, Windows

image

This article is from: 

Blending apps and sites with the HTML x-ms-webview