How to create a QuickLink (HTML)

Applies to Windows only

Users want their ability to share content with friends and family to be an extension of their computer experience. Apps that embrace this concept create an environment that enables users to share content quickly and easily. By supporting the Share Target contract, you can make the sharing experience even easier by using a custom shortcut called a QuickLink. A QuickLink acts as a link to your app that's customized for a specific set of user actions.

When users share content, they typically want to make choices about how to share their content and who to share it with. A common example of this is sharing through email. If a user wants to share something through email, they have to supply the email addresses of the people they want to share with. Even though a user might not mind supplying these email addresses the first time, manually adding them again during subsequent sharing sessions becomes tedious. A better experience is for the email app is to create a QuickLink to apply next time the choices that the user made last time.

A QuickLink doesn't actually store any data. Instead, it contains an identifier that, when selected, is sent to your app. For QuickLinks to work, your app needs to store the data somewhere—such as in the cloud, or on the user's computer—along with its associated ID. There are lots of ways you can do this—for one way of storing data, see Managing application data.

To learn more about supporting the Share Target contract, see QuickStart: Receiving shared content. That topic describes the basic steps your app needs to follow when users select it to share content.

What you need to know

Technologies

Prerequisites

  • You should be familiar with Microsoft Visual Studio and its associated templates.
  • You should be familiar with JavaScript.
  • You should know how to receive shared content, as described in QuickStart: Receiving shared content.

Instructions

Step 1: Create a QuickLink object.

The QuickLink object is part of the ShareOperation class.


var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();


Step 2: Add an ID to the QuickLink.

After you have an instance of the QuickLink object, you need to first configure it with a target ID string that the system can return to your app when the user selects the QuickLink. The following example shows how to set up a target ID.


quickLink.id = "123456789";


Step 3: Add a title to the QuickLink.

Next, specify a title for the QuickLink. A title helps the user identify the QuickLink and its purpose.


quickLink.title = document.getElementById("quickLinkTitle").value;

// For quicklinks, the supported FileTypes and DataFormats are set 
// independently from the manifest.
var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
quickLink.supportedFileTypes.replaceAll(["*"]);
quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, 
    dataFormats.bitmap, dataFormats.storageItems, dataFormats.html, customFormatName]);

Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
    quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
});


Step 4: Specify the supported file types

Next, you need to specify what file types and data formats the QuickLink supports. The system shows the QuickLink only when the DataPackage shared from the share source application contains one of these file types or data formats.


var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
quickLink.supportedFileTypes.replaceAll(["*"]);
quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, 
    dataFormats.bitmap, dataFormats.storageItems, dataFormats.html, customFormatName]);


Step 5: Add a thumbnail to the QuickLink.

We recommend that you use the same icon that users would see if they were selecting your app without a QuickLink. That way, the user knows that the link is associated with your app.


Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
    quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
});

Step 6: Send the QuickLink to the system.

When you've finished creating the QuickLink, you can send it to the system by calling the ShareOperation.reportCompleted method.


shareOperation.reportCompleted(quickLink);


Complete example

The following function creates and returns a QuickLink. Call this function after your app finishes a share operation, instead of calling ShareOperation.reportCompleted directly.


function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = document.getElementById("quickLinkTitle").value;
    
    // For quicklinks, the supported FileTypes and DataFormats are set 
    // independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, 
        dataFormats.bitmap, dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

Related topics

Sharing content target app sample
Sharing and exchanging data
Quickstart: Receiving shared content
QuickLink
ShareOperation
Windows.ApplicationModel.DataTransfer
Windows.ApplicationModel.DataTransfer.Share
Guidelines for debugging target apps

 

 

Show:
© 2014 Microsoft