How to link to external web pages (HTML)

Article
04/18/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how to link to external web pages and display them in your app.

Prerequisites

We assume that you know how to create a basic app. If you need help with this, see Create your first app using JavaScript.

Instructions

Linking to an external web page

To link to an external web page, just add a hyperlink to your HTML. This example creates a link to www.bing.com. When you click the link, it opens in the web browser (rather than in your app).


<p><a href="https://www.bing.com">Search the web</a></p>

Displaying an external web page in your app

Your app can display external an external page in an iframe, but you can't navigate your top-level page to an external web page.

Hh780594.wedge(en-us,WIN.10).gif To display an external web page in your app

Create an iframe to display the web page. Set the iframe element's name attribute.
```
<iframe name="targetFrame">
</iframe>
```
Create a link to the external website. Set its target attribute to the name of the iframe you created in the previous step.
```
<p><a href="https://www.bing.com" target="targetFrame" >Search the web</a></p>

<iframe name="targetFrame">
</iframe>
```
When you run the app and click the link, the link opens in inside your application. The page runs in the web context and has limited access to the system compared to pages included in your app's package.

When displaying an external web page in an iframe, it's good idea to provide a custom error page in case there is an issue with the page. For an example of how to do this, see the XHR, handling navigation errors, and URL schemes sample.

Note For performance reasons, Windows Store apps may cache remote content indefinitely. As a result, your app might not show recent script or CSS updates. Uninstalling and reinstalling the app clears the cache. Other solutions include a random parameter in the query string or setting up the web server so that it doesn't cache. For more info, see How to prevent caching in Internet Explorer.

About local and web contexts

Pages you include in the app itself generally run in the app's local context. When you use an iframe to navigate to a remote page, that page runs in the web context and has limited access to your system.

Local context pages and scripts have access to different features than pages and scripts in the web context. They can access the Windows Runtime and perform cross-domain XHR requests, for example. Both local and web context pages can access the Windows Library for JavaScript.

For more information about the different features available to local and web context pages, see Features and restrictions by context.

You can use the ApplicationContentUriRules section of the app's package manifest to give a page in the web context access to your system's geolocation devices (if your app has permission to access this functionality), as well as access to the clipboard.

Hh780594.wedge(en-us,WIN.10).gif To give a web context page additional access

To give a page in the web context additional access, you create a Content Uri rule. In the Microsoft Visual Studio solution explorer, right-click your app's package.appxmanifest file and select View Designer. The manifest designer appears.
In the URI column, specify the URI of the web page to include.

There are several ways to specify a URI match:
- You can specify an exact hostname
- You can specify a hostname for which a URI with any subdomain of that hostname is included or excluded
- You can specify an exact URI
- You can specify an exact URI that can contain a query property
- You can specify a partial path and use a wildcard to indicate a particular file extension for an include rule.
- You can use relative paths for exclude rules but not for include rules.
For this example, set the URI to https://www.bing.com/*.

Note If you have more then one subdomain, you must use one wildcard for each subdomain. For example, "https://*.microsoft.com" matches with "https://"any".microsoft.com" but not with "https://"this"."any".microsoft.com."
The Rule drop-down lets you specify whether the URI should be included or excluded. Set it to include.
Click Add new URI to add the rule. Behind the scenes, the designer adds a new Rule element to the ApplicationContentUriRules section of your package manifest file.
```
      <ApplicationContentUriRules>
        <Rule Match="https://www.bing.com/*" Type="include" />
      </ApplicationContentUriRules>
```

Navigating from web to local context pages

You can't navigate from a web context page back to a local context page unless you call the MSApp.addPublicLocalApplicationUri from a local context page and pass it the URI of the page that you want web context pages to be able to navigate to. For example, if you want a web context page to be able to navigate to a page in your app named "page2.html", use this code:

MSApp.addPublicLocalApplicationUri("page2.html");

Web context pages can now navigate to page2.html. You have to call this method once for each local context page that you want to be accessible to web context pages.

Warning If you have a page that accepts query parameters and you allow any place on the web to navigate to it, the external web page could pass malicious query parameters.

Features and restrictions by context