Quickstart: Sharing content (Windows Store apps using JavaScript and HTML)

Windows 8 provides a robust set of content sharing APIs that can help you connect your users with the people they care about and the apps they use most.

Successful apps make it easy for users to share content in a flexible manner. Integrating share into your app allows content to flow out of your app in ways that align with your app’s goals. If users regularly share content from your app, your app will gain visibility and be more deeply integrated into the Windows 8 experience.

To learn how to use these APIs, read on. If you’re 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

To use the code described in this section, you'll need:

• Windows 8
• Microsoft Visual Studio Express 2012 for Windows 8

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 that your app use a delegate any time that the data a user wants to share is resource-intensive, because a delegate can help your app share data more efficiently. For more about delegates, see Sharing and delegates later in this topic.

Choosing properties

When you package data for sharing, you can supply a variety of properties that provide additional information about the content being shared. Taking advantage of these properties can help your target app 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. Similarly, adding a thumbnail when sharing an image or a link to a webpage 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 a user presses the Share charm. Your app needs to listen for this event to know when the user wants to share data from your app.

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

The previous 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

If letting the user invoke share through the Share charm is not the most ideal option for your app, you can invoke the share pane programmatically (for examples, see Guidelines for sharing content). The following example shows how.

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, 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:

• Sharing content source app sample
• Sharing content target app sample
• Quickstart: Receiving shared content
• How to share text
• How to share a link
• How to share HTML
• How to share an image
• How to share files

Related topics

Choosing data formats for sharing

Guidelines and checklist for sharing content

Quickstart: Receiving shared content

Build date: 12/5/2012