How to share HTML (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]
Sharing HTML content is different from other basic formats such as text or a link. The main challenge is that the content a user selects might contain references to other elements. Apps that support sharing HTML need to consider how to handle these references to ensure that users share the content they want.
A typical situation that demonstrates the challenge of sharing HTML, is content that contains both text and an image. When users select this content and tap the Share charm, they expect to share both the text and the image. However, the HTML doesn't contain the image—it contains an img tag that points to where the image resides. You need to set up a resource map if the image reference isn’t accessible to a target app, such as a locally stored image.
To help you ensure that you can share HTML in a way that users expect, the Windows.ApplicationModel.DataTransfer namespace includes a few functions that help capture referenced elements, such as images. We'll show you how.
What you need to know
Technologies
Prerequisites
- You should be familiar with Visual Studio and its associated templates.
- You should be familiar with JavaScript.
- You should know how to use JavaScript to identify HTML that a user has selected, and find instances of child elements like img tags within that selection.
Instructions
Step 1: Set up your app as a share source
The DataTransferManager object is the main starting point for any share operation. Add a DataRequested event handler to fire when the user wants to invoke Share. In a Windows Store app, this occurs automatically when the user invokes the Share charm. If you're developing for Windows Phone, there is no built-in Share charm, so you'll need to add a control for the user to tap and trigger the handler.
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareHtmlHandler);
The remaining steps are for implementing the shareHtmlHandler function.
Step 2: Get a DataRequest object
When a datarequested event occurs, your app receives a DataRequest object. This object contains a DataPackage that you can use to provide the content that the user wants to share.
var request = e.request;
Step 3: Set the title and description properties
request.data.properties.title = "Share Html Example";
request.data.properties.description =
"Demonstrates how to share an HTML fragment with a local image.";
Step 4: Use the createHtmlFormat method to format the fragment
The createHtmlFormat function wraps the HTML format with the headers and other information the system needs to share the content.
var localImage = "ms-appx:///images/logo.png";
var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
var htmlFormat =
Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);
Step 5: Add the HTML to the DataPackage
To add the HTML, use the setHtmlFormat function.
request.data.setHtmlFormat(htmlFormat);
Step 6: Create a RandomAccessStreamReference of the local image
var streamRef =
Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));
Step 7: Add the RandomAccessStreamReference to the resource map
To add the image file, use the resourceMap property.
request.data.resourceMap[localImage] = streamRef;
If the HTML fragment being shared contains multiple local images, you'll need to repeat this step for each local image.
Complete example
Here's an example of a function that sets some HTML for a user to share. For a more complete example, check out our code gallery sample.
function shareHtmlHandler(e) {
var localImage = "ms-appx:///images/logo.png";
var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
var request = e.request;
request.data.properties.title = "Share Html Example";
request.data.properties.description = "Demonstrates how to share an HTML fragment with a local image.";
var htmlFormat = Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);
request.data.setHtmlFormat(htmlFormat);
var streamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));
request.data.resourceMap[localImage] = streamRef;
}
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
// This app is newly launched; register the app as a share source.
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareHtmlHandler);
} else {
// TODO: This app was reactivated from suspension.
// Restore the app state here.
}
args.setPromise(WinJS.UI.processAll());
}
};
Related topics
Sharing content source app sample