Choosing data formats for sharing (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]

Whether you're writing a source app, which helps users share content, or a target app, which receives that content, you should take the time to consider what data formats and file types you want to support. Here, we'll describe the standard formats that the Windows.ApplicationModel.DataTransfer namespace supports, and how to create and use custom formats when the standard formats don't apply.

Choosing data formats for a source app

If you're writing a source app, you aren't limited to just one data format or file type. While it's likely that one format makes more sense than the others, by supplying the same data in other formats you can help to ensure that users can share by using the target app of their choice. For example, if a user wants to share formatted text, such as from a webpage, you might also want to supply a plain-text version of the content, because not every target app supports formatted text.

Note  The number of additional formats that you support depends on the type of content your users might share. It's important to consider what the content is and what the user expects when they share it. Creating a plain-text version of formatted text, for example, often makes sense. Creating a link to a webpage that contains that text, however, is probably not what the user expects.

 

Example scenario: The user wants to share an article they’re reading in your app. If the content is available on the web, first include a link to the article. Additionally, you should include an abstract of the article with a link back to the source in HTML format, as well as text.

Example scenario: The user wants to share a selection from the article in your app. In this case, the HTML format most accurately reflects the user’s intent. You should also include a text version of the user’s selection. The recommended way to achieve this is to use MSApp.createDataPackageFromSelection.

This table can help you decide what formats you should support as a source app.

Primary data type your app supports Recommended primary DataPackage format Additional recommendations
Unformatted plain text Text WebLink, if the text is a webpage link.
Link WebLink Text
Formatted content/HTML HTML

Text, if the content contains only text.

WebLink, if the content is a link.

File StorageItems
Single Image StorageItems
Multiple files and images StorageItems

 

Custom formats are also supported for situations in which you want to be more specific than the standard formats allow. These custom formats can either be based on standard data schemas, such as those found on http://www.schema.org, or a format that you define that's unique to your app.

Choosing data formats for a target app

For a target app, we recommend that you try to support as many format types as possible. This helps to ensure that your app is available as an option whenever the user wants to share. However, just like source apps, you shouldn't support a particular format if you don't plan to receive that type of data. For example, an app that accepts only text shouldn't register that it supports bitmaps.

Here are some recommendations for what formats you should support.

Primary data type your app supports Recommended primary DataPackage format Additional recommendations
Unformatted plain text Text
Link WebLink Text
Formatted content/HTML HTML

Text

WebLink

File StorageItems
Single Image StorageItems
Multiple files and images StorageItems
Specific file types (such as .docx) StorageItems with specific file name extensions

 

If your app can support multiple formats, and all those formats are present in the content being shared, we recommend that you process only the format that is the most relevant to your app. For example, if your app shares links, and it receives shared content that has both a link and some text, your app should process only the link.

Sometimes, your app might benefit from receiving data that includes more information than the standard formats provide. For example, a library app might want to receive text, but only if that text has information about a book. Custom formats are supported for such situations. These custom formats can either be based on standard data schemas, such as those found on http://www.schema.org, or a format that you define that's unique to your app.

Using schema-based formats

There are lots of times where the data that you want to share (either as a source or as a target app) is more specific than the standard formats provide. For example, a movie-focused app might want to share information about movies, and want details such as the title, rating, director, and so on. A book-focused app might want to share information about books, including author, title, and publication date. If your app falls into a category like this, we recommend that you support one of the many schemas listed on http://www.schema.org.

If you want to share data using one of these schemas, here's how you do it:

  1. Identify the item (book, movie, and so on) that the user wants to share.
  2. Collect the information related to the item and package it in JavaScript Object Notation (JSON) format.
  3. Use setData to add the content to a DataPackage. When you do, you have to include a format ID. For now, use http://schema.org/<schema> as the ID. For example, http://schema.org/Book.

This example illustrates how to share data in a custom format.

var book = {
    "type" : "http://schema.org/Book",
    "properties" : 
    {
         "image" : "http://sourceurl.com/catcher-in-the-rye-book-cover.jpg",
         "name" : "The Catcher in the Rye",
         "bookFormat" : "http://schema.org/Paperback",
         "author" : "http://sourceurl.com/author/jd_salinger.html",
         "numberOfPages" : 224,
         "publisher" : "Little, Brown, and Company",
         "datePublished" : "1991-05-01",
         "inLanguage" : "English",
         "isbn" : "0316769487"
    }
};
book = JSON.stringify(book);

function shareCustomData() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", function (e) {
        var request = e.request;
        request.data.setData("http://schema.org/Book", book);
    });
}

Notice that we put only a single data format in the DataPackage. That way, any target apps that the user selects will know what to expect.

If you want to receive data that uses one of these schemas, here are the steps you need to follow:

  1. Edit your package manifest to declare that your app is a share target. See our Quickstart to learn how to do this.
  2. In your package manifest, add a data format that identifies the schema that your app supports. Use http://schema.org/<schema> as the data format. For example, http://schema.org/Book.
  3. Use getDataAsync to get the content from the DataPackageView object that you receive during a share operation.

This example illustrates how to receive data shared in a custom format.

if (shareOperation.data.contains("http://schema.org/Book")) {
    shareOperation.data.getTextAsync(("http://schema.org/Book").done(function (customFormatString) {
        var customFormatObject = JSON.parse(customFormatString);
        if (customFormatObject) {
            // This sample expects the custom format to be of type http://schema.org/Book
            if (customFormatObject.type === "http://schema.org/Book") {
                customFormatString = "Type: " + customFormatObject.type;
                if (customFormatObject.properties) {
                    customFormatString += "\nImage: " 
                            + customFormatObject.properties.image
                            + "\nName: " + customFormatObject.properties.name
                            + "\nBook Format: " + customFormatObject.properties.bookFormat
                            + "\nAuthor: " + customFormatObject.properties.author
                            + "\nNumber of Pages: " + customFormatObject.properties.numberOfPages
                            + "\nPublisher: " + customFormatObject.properties.publisher
                            + "\nDate Published: " + customFormatObject.properties.datePublished
                            + "\nIn Language: " + customFormatObject.properties.inLanguage
                            + "\nISBN: " + customFormatObject.properties.isbn;
                }
            }
        }
    });
}

Using custom formats

If you're unable to find a schema on http://schema.org/docs/full.htm that meets the needs of your app, you also have the option of creating your own custom format. If you decide to do that, there are few key things you need to remember:

  • The name of the custom format is important. The same name must be used by both the source app and the target app.
  • You must publish the format. That way, developers who want to use the format know how they need to package the content.

We cover these and other considerations in more detail in Guidelines for creating custom data formats.

Sharing content source app sample

Sharing content target app sample

Quickstart: Sharing content

Quickstart: Receiving shared content