How to create a QuickLink (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]
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
Quickstart: Receiving shared content
Windows.ApplicationModel.DataTransfer