How to share HTML (XAML)
[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 users can share HTML in a way that they 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 templates.
- You should be familiar with developing in C#.
- You should know how to identify HTML that a user has selected, and find instances of child elements like img tags in that selection.
Instructions
Step 1: Add the DataTransfer namespace
First you need to add the right namespaces to your app so you can create and process the objects related to sharing. At a minimum, you should add the Windows.ApplicationModel.DataTransfer namespace:
using Windows.ApplicationModel.DataTransfer;
using namespace Windows::ApplicationModel::DataTransfer;
This namespace has all that you need for basic sharing. Remember, though, if you want to share content such as images or files, you'll need to add those namespaces as well. Here's a list of the namespaces you might need:
- Windows.Storage. Needed for working with StorageFile and other objects.
- Windows.Storage.Pickers. Used to open the file picker so users can select images and files.
- Windows.Storage.Streams. Often used when sharing images, files, and custom-formatted data.
- Windows.Graphics.Imaging. Useful if you need to modify images before sharing them.
Step 2: Get the DataTransferManager object
The DataTransferManager object is the starting point for any sharing operation.
DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();
DataTransferManager^ dataTransferManager = DataTransferManager::GetForCurrentView();
Step 3: Add an event handler for the DataRequested event
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.
dataTransferManager.DataRequested += new TypedEventHandler<DataTransferManager,
DataRequestedEventArgs>(this.ShareHtmlHandler);
auto dataRequestedToken = dataTransferManager->DataRequested +=
ref new TypedEventHandler<DataTransferManager^, DataRequestedEventArgs^>(
this, &MainPage:: ShareHtmlHandler);
Step 4: 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.
DataRequest request = e.Request;
DataRequest^ request = e->Request;
Step 5: Set the title and description properties
The title property is mandatory and must be set.
// The title is mandatory
request.Data.Properties.Title = "Share Html Example";
request.Data.Properties.Description = "Demonstrates how to share an HTML fragment with a local image.";
// The title is mandatory
request->Data->Properties->Title = "Share Html Example";
request->Data->Properties->Description = "Demonstrates how to share an HTML fragment with a local image.";
Step 6: 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.
string htmlFormat = HtmlFormatHelper.CreateHtmlFormat(htmlExample);
String^ htmlFormat = HtmlFormatHelper::CreateHtmlFormat(htmlExample);
Step 7: Add the HTML to the DataPackage
To add the HTML, use the SetHtmlFormat function.
request.Data.SetHtmlFormat(htmlFormat);
request->Data->SetHtmlFormat(htmlFormat);
Step 8: Create a RandomAccessStreamReference of the local image
You need to complete the remaining steps only if the HTML contains local images. In that case, you need to add each local image to the ResourceMap property of the DataPackage so that the target app has access to it.
RandomAccessStreamReference streamRef = RandomAccessStreamReference.CreateFromUri(new Uri(localImage));
RandomAccessStreamReference^ streamRef = RandomAccessStreamReference::CreateFromUri(ref new Uri(localImage));
Step 9: Add the RandomAccessStreamReference to the resource map
To add the image file, use the ResourceMap property.
request.Data.ResourceMap[localImage] = streamRef;
request->Data->ResourceMap->Insert(localImage, streamRef);
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.
private void RegisterForShare()
{
DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();
dataTransferManager.DataRequested += new TypedEventHandler<DataTransferManager,
DataRequestedEventArgs>(this.ShareHtmlHandler);
}
private void ShareHtmlHandler(DataTransferManager sender, DataRequestedEventArgs e)
{
DataRequest 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.";
string localImage = "ms-appx:///Assets/Logo.png";
string htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
string htmlFormat = HtmlFormatHelper.CreateHtmlFormat(htmlExample);
request.Data.SetHtmlFormat(htmlFormat);
// Because the HTML contains a local image, we need to add it to the ResourceMap.
RandomAccessStreamReference streamRef =
RandomAccessStreamReference.CreateFromUri(new Uri(localImage));
request.Data.ResourceMap[localImage] = streamRef;
}
void MainPage::RegisterForShare()
{
DataTransferManager^ dataTransferManager = DataTransferManager::GetForCurrentView();
auto dataRequestedToken = dataTransferManager->DataRequested +=
ref new TypedEventHandler<DataTransferManager^, DataRequestedEventArgs^>(
this, &MainPage::ShareHtmlHandler);
}
void MainPage::ShareHtmlHandler(DataTransferManager^ sender, DataRequestedEventArgs^ e)
{
DataRequest^ 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.";
String^ localImage = "ms-appx:///Assets/Logo.png";
String^ htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
String^ htmlFormat = HtmlFormatHelper::CreateHtmlFormat(htmlExample);
request->Data->SetHtmlFormat(htmlFormat);
// Because the HTML contains a local image, we need to add it to the ResourceMap.
RandomAccessStreamReference^ streamRef =
RandomAccessStreamReference::CreateFromUri(ref new Uri(localImage));
request->Data->ResourceMap->Insert(localImage, streamRef);
}
Related topics
Sharing content source app sample
Windows.ApplicationModel.DataTransfer