Quickstart: Supporting custom data formats (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]
The fundamental class that lets you share data between apps —the DataPackage— supports two kinds of formats: standard and custom. The DataPackage supports standard formats with strongly-typed methods such as setText or getHtml. Custom formats, on the other hand, let you define more targeted formats that can provide a better user experience.
If you'd like to learn more about custom formats, and what you should consider before implementing one in your app, see Guidelines for creating custom data formats.
Before you begin
If you're here, we're assuming you already have a custom format that your app uses, and you want to know how to share data using that format with other apps. If you're still deciding if using a custom format is the right way to go, see our topic, Guidelines for creating custom data formats.
Sharing data using a custom format
To share data using a custom format, you first need to get an instance of the DataPackage object. On Windows 8.1, the following code uses an event listener to detect when the user taps the Share charm, and then gets a DataPackage object. If you're developing for Windows Phone 8.1, 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 dataTransferManager = DataTransferManager.GetForCurrentView();
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
At this point, you need to collect the data that the user wants to share. How you do this, depends on the custom format you defined. The following code uses a format the DataPackage does not directly support—comma-separate values, or CSVs—as a custom format.
function shareCustomData() {
//Create the custom data.
var myArray = new Array(1, 2, 3, 4);
var arrayToCsv = myArray.join(",");
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", function (e) {
var request = e.request;
request.data.properties.title = "Share Text Example";
request.data.properties.description = "A demonstration that shows how to share.";
request.data.setData("csv", arrayToCsv);
});
}
Notice that, to share your data, you use the setData method of the DataPackage. This method takes two parameters, including the name of the custom format, and the data itself.
request.data.setData("csv", arrayToCsv);
At this point, it's worth pointing out a couple of things:
- For a custom format to function correctly, the name of format must be the same in both the source app and the target app. For this reason, we recommend that you test your custom formats with the apps you think a user might select. If you created the custom format, be sure to provide a way for other developers to discover it. We have more information on these and other considerations in Guidelines for creating custom data formats.
- Second, even if a custom format provides the best experience for users, it's probably a good idea to provide a version of the data in a standard format. That way, you account for situations in which users want to share content using an app that doesn't recognize your custom format.
Receiving data in a custom format
To receive data shared using a custom format, you need to declare that your app is a share target and update your package manifest file with the format type.
To declare that your app is a share target:
- Open the manifest file. It should be called something like package.appxmanifest.
- Open the Declarations tab.
- Choose Share Target from the Available Declarations list.
To specify the format type:
- Open the manifest file.
- In the Supported File Types section, click Add New.
- Type the extension for the format type. You need to include the period (.).
Next, you need to know if your app was activated for a share operation.
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
// Code to handle activation goes here.
}
After your app activates, you use the ShareOperation object to get the data being shared..
shareOperation = eventObject.detail.shareOperation;
Next, your app can use the Contains method to detect if the DataPackageView has data stored in the custom format.
if(shareOperation.data.contains("customformat")) {
//Process the data here.
}
To get the data, use the getDataAsync method.
shareOperation.data.getTextAsync(customFormatName).then(function (customFormatString) {
// Process the custom data
});
How your app processes the data depends on the custom format the source app used.