How to receive text (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]
Text is perhaps the most common of all data formats that users share. In addition to being the first choice for content such as status updates, it is a recommended option for apps that share links, HTML, and other information.
When writing a target app, you should usually support text as a part of sharing. It ensures that users can select your app in a wide variety of situations. That said, do not support text if you think it will only confuse users. For example, if your app deals mostly with files, a text representation of those files isn't going to meet user expectations.
What you need to know
Technologies
Prerequisites
- You should be familiar with Visual Studio and its associated templates.
- You should be familiar with JavaScript.
Instructions
Step 1: Support the Share contract
Before your app can receive shared content, you have to declare that it supports the Share contract. This contract essentially lets the system know that your app is available to receive content. If you're using a Microsoft Visual Studio template to create your app, here's how you support the Share contract:
- Open the manifest file (package.appxmanifest).
- Open the Declarations tab.
- Choose Share Target from the Available Declarations list.
- Click Add to add support for the Share Target contract in your app.
Step 2: Specify that your app supports text
When writing a target app, you can specify both file types and formats. To specify the file types you support:
- Open the manifest file.
- In the Supported File Types section, click Add New.
- Type .txt. You need to include the period (.) before "txt" but not the one after.
To specify that you support text as a data format:
- Open the manifest file.
- In the Data Formats section, click Add New.
- Type "text" (without the quotes).
The preceding steps add the following section to the manifest:
<Extensions>
<Extension Category="windows.shareTarget">
<ShareTarget>
<DataFormat>text</DataFormat>
</ShareTarget>
</Extension>
</Extensions>
Note You can specify a different entry point when your app is activated for the Share Target contract. To do this, modify the Start page entry in App settings section of the Share Target declaration in the package manifest. We highly recommend that you also use a separate JavaScript file that handles activation for this page. For an example, check out the Sharing content target app sample.
Step 3: Add an event handler to detect when your app is activated.
When a user selects your app to share content, the system activates your app. Because there are many ways this can happen, you need to add code that detects why the activation occurred. You do this by checking the value of the kind property.
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
// The application has been launched. Initialize as appropriate.
} else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
...
}
};
Step 4: Get the ShareOperation object.
The ShareOperation object contains all the data that your app needs to get the content that a user wants to share.
shareOperation = args.detail.shareOperation;
Step 5: Return from the activated event handler quickly.
The activated event handler must return quickly. Queue an asynchronous event from activated event handler so that share data processing takes placed after the activated event returns.
WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });
The remaining steps implement the shareReady function.
Step 6: Check to see if the share data contains text.
The shareOperation.data property contains a DataPackageView object. This object is essentially a read-only version of the DataPackage object that the source app used to create the data. Use this object to see if the content being shared is available in text format.
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
// Code to process text goes here.
}
Checking whether the DataPackage contains the data format you are interested in is good practice, even if your app supports only one format. This makes it easier to support other data formats later.
Step 7: Process the text.
To get the text, call the DataPackageView.getText method.
shareOperation.data.getTextAsync().done(function (text) {
// To output the text using this example,
// you need a div tag with an id of "output" in your HTML file.
document.getElementById("output").innerText = text;
});
Of course, what you do with the text depends on your app.
Step 8: Call reportCompleted.
After your app successfully finishes sharing the content, call reportCompleted. After you call this method, the system dismisses your app.
shareOperation.reportCompleted();
Remarks
Check out our Sharing content target app sample code sample to see the entire end-to-end experience of an app receiving text as part of sharing.
var shareOperation = null;
function shareReady(args) {
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
shareOperation.data.getTextAsync().done(function (textValue) {
// To output the text using this example, you need a div tag with an
// id of "output" in your HTML file.
document.getElementById("output").innerText = textValue;
});
}
}
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
// The application has been launched. Initialize as appropriate.
args.setPromise(WinJS.UI.processAll());
} else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
// This app has been activated share.
args.setPromise(WinJS.UI.processAll());
// We receive the ShareOperation object as part of the eventArgs.
shareOperation = args.detail.shareOperation;
// We queue an asychronous event so that working with the ShareOperation object
// does not block or delay the return of the activation handler.
WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });
}
};
Related topics
Sharing content target app sample
Quickstart: Receiving shared content
Windows.ApplicationModel.DataTransfer