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());
    }
};

Sharing content source app sample

Sharing and exchanging data

How to share files

How to share a link

How to share text

Quickstart: Sharing content

DataPackage

Windows.ApplicationModel.DataTransfer

Windows.ApplicationModel.DataTransfer.Share