How to reference content (HTML)
[ 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 the different URL schemes used by Windows Runtime apps using JavaScript and how to use them to refer to content.
Prerequisites
- We assume that you can create a basic Windows Runtime app using JavaScript. For help creating your first app, see Create your first Windows Runtime app using JavaScript.
Instructions
URLs and schemes
Every HTML page has is loaded from a specific URL of the general form <scheme>://<domain name>/<path>. When a page is loaded, if the scheme and domain name are omitted from references to resources in the markup of the page, they are assumed to match the URL of the current page.
In Windows Runtime apps using JavaScript, files are loaded from the app’s package. The scheme that is used to reference the app’s locally-packaged files is "ms-appx:". The domain name can either be the package name (the first part of the package full name, omitting the publish hash) or, more commonly, omitted. If it is omitted, the app assumes you mean the app’s package full name. For example, a reference to "ms-appx:///default.html" (note the three slashes because the domain name has been omitted) is resolved to the default.html file in the root of the local app package.
You can also use "/" to refer to the package root. For example, "/default.html" resolves to the default.html file in the root of the local app package.
For more info and additional examples, see How to load file resources.
The file:// schema
You can't use the file:// schema in references because it's blocked for security reasons. Use the "ms-appdata:" scheme to refer to app data or one of the other schemes described in the previous section to refer to packaged resources. You can't reference resources that aren't app data or packaged resources unless you obtain an IStorageItem and then use URL.createObjectURL to obtain a URL.
Referring to files in dependent packages
If, however, you wish to refer to a file in a dependent package you may specify the name of that package as the domain name.
Relative paths
You may, of course, reference a file by path only, either relative to the root of the package, or relative to the current document. For example, if the top-level document is loaded from "ms-appx:///html/info.html", then a reference to an image source URL of "/images/picture.jpg" would be relative to the root of the package, whereas a URL of "../picture.jpg" would be located in the same folder as the "images" folder.
Schemas and contexts
The top-level document of your app is loaded via the "ms-appx:" scheme and runs in the local context. Likewise, an iframe whose source is loaded via the "ms-appx:" scheme is also running in the local context. If an iframe whose source is loaded from the "http:" or "https:" schemes is running in the web context. Apps and iframe elements running in the local context have certain abilities and restrictions that those running in the web context do not, and vice versa. For example, the local context can access the Windows Runtime, and the web context can easily refer to remote content. In general, local contexts are used for any packaged code that needs to access a Windows Runtime API, and web contexts are used to refer to external web content within an iframe, such as "https://www.microsoft.com". If you wish to create an iframe loaded from locally-packaged content that runs in the web context, you must use a different scheme, "ms-appx-web:". Content referenced via this scheme is loaded from the local package, but runs with the abilities and restrictions of the web context.
App data
Sometimes it is useful to refer to resources you have downloaded from the Internet to your app’s local ApplicationData storage (via Windows Runtime APIs). To refer to such content, you must use the scheme "ms-appdata:", with the path to the file within your ApplicationData local storage. Note that, for security reasons, you cannot navigate to HTML you have downloaded to this location and you cannot run any executable or potentially executable code, such as script or CSS. It is intended for media such as images or videos and the like.
App resources
You may refer to resources that are included in your app, such as localized images, via the scheme "ms-resource:".