Del via

Quickstart: Sharing content (HTML)

  • Artikkel

[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]

Successful apps make it easy for users to share what they are doing with their friends and family. Apps that make it easy for users to share content often see an increased awareness of the app, and that encourages users to use the app more often.

To learn how to use these APIs, read on. If you’re more interested in learning how your app can receive shared content, see Quickstart: Receiving shared content.

Objective: After reading through this quickstart, you should have a good idea how to share content.

Prerequisites

  • You should be familiar with Visual Studio and its templates.
  • You should be familiar with developing in HTML and JavaScript.

Instructions

Choosing data formats

At the core of any sharing operation is the DataPackage object. This object contains the data the user wants to share. The types of content that a DataPackage can contain include:

  • Plain text
  • Uniform Resource Identifiers (URIs)
  • HTML
  • Formatted text
  • Bitmaps
  • Files
  • Developer-defined data

A DataPackage object can contain one or more of these formats, in any combination. In addition, a DataPackage can contain a delegate—a function that is called when the receiving app requests data. We recommend using a delegate any time that the data a user wants to share is resource-intensive, as a delegate can help your app share data more efficiently.

Choosing properties

When you package data for sharing, you have the option to supply a variety of properties that provide additional information about the content being shared. Taking advantage of these properties can help target apps improve the user experience. For example, providing a title and description that conveys what the user is sharing can help when the user is sharing content with more than one app. Adding a thumbnail when sharing an image or a link to a web page can provide a visual reference to the user. For more information on what properties are available for you to use, check out our documentation on DataPackage.DataPackagePropertySet.

Setting up your share source

To set up your application as a share source app, you first need to get the instance of the DataTransferManager class that’s been assigned to the current window.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();

This class supports a DataRequested event, which is fired 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.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

The above example registers an event handler that is called whenever a datarequested event is fired. The handler receives a DataRequest object that your app uses to set the data that the user wants to share from your share source app.

Any content that you share must contain two properties: a title and the content itself. In addition, we also recommend that you include a description property for better clarity.

The following code builds on the previous examples and shows how to share plain text with a target app.

function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Text Example";
    request.data.properties.description = "Demonstrates how to share text.";
    request.data.setText("Hello World!");
}

Sharing and delegates

Sometimes, it is not desirable to prepare data right away when the user invokes sharing. For example, if your app supports several different data formats, it's not efficient to create all of the formats immediately. It's better to wait until the target app specifies the format that it wants, and then generate only the data requested. To accomplish this, you configure the DataPackage object to populate only the needed data through a delegate call upon request.

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

To learn more details about this type of sharing, check out How to share files.

Invoking the share pane programmatically

After you set your content for sharing, it's ready to go. All the user needs to do is select the app to receive the content. For those situations in which using the charm isn't ideal—such as to share a high score on a game—you can also launch the Share charm programmatically.

Note  

The Charms bar does not exist on Windows Phone 8.1, so you must include the share option programmatically. It can either be accessible at all times as part of an app bar, or be associated with a specific control on a particular page.

function showShareUI() {
    Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
}

Handling errors and other issues

In most cases, providing content is a straightforward process. However, there are situations where your app may not be able to share. To help you handle these situations on Windows 8.1, the DataRequest object supports a FailWithDisplayText method. Use this method to display a text message to the user if the user can't share from a particular view or needs to perform additional steps before sharing. For example, the app might require the user to select content for sharing but the user didn't select any.

Summary and next steps

You should now have a good understanding of how sharing works.

To learn more, or to get more specific examples of how to add sharing to your app, take a look at:

Choosing data formats for sharing

Guidelines and checklist for sharing content

Quickstart: Receiving shared content