1+1=3: Using app contracts to integrate with Windows 8 experiencesJaime RodriguezWindows Evangelist3-100

Reimagine connected apps

Most apps have rich content that users want to..

Find and act upon Share Save or enhance in other apps Print Send to devices…

Contracts are agreements between apps and the operating system to accomplish a common task in a manner.

consistent, easily accessible

Windows 8 contracts

Share Search Settings Play To File Picker Cached file updater

Contracts in action

Demo

Windows does the heavy lifting, you focus on the scenario

Share contract

Sharing

Share source

Share target

Sharing from source to target Source app Operating

system Share target app

Registers with the DataTransfer Manager

Receives event and fills DataPackage

User selects “Share”, active app is sent event

Filters list of Target Apps and Quicklinks

User selects Target App or Quicklink

Activated for sharing Activate Target as kind shareTarget Processes

DataPackage contents

Reports Complete DataPackage lives in source application

Completes async calls and returns

//Step 1: Listen for DataTransferManager.datarequested var dtmns = Windows.ApplicationModel.DataTransfer.DataTransferManager; var dataTransferManager = dtmns.getForCurrentView(); dataTransferManager.addEventListener("datarequested", dataRequestHandler);

/* Step2: In datarequested handler, add title, description, and data in supported formats.*/

function dataRequestHandler ( e ) { var request = e.request;

request.data.properties.title = “Title is required” ;

request.data.properties.description = “Description is optional” ;

request.data.setText(“Hi mom!”);

}

Implementing share source

Implementing share source

Demo

//Step 1: Declare contract in app manifest

//Step 2: Handle app activation

//Step 3: Handle share operation

//Step 4: Create a QuickLink to return (Optional)

//Step 5: Report extended status and completion

Implementing share target

<Extensions> <Extension Category="windows.shareTarget" StartPage="target.html">

<ShareTarget>

<DataFormat>text</DataFormat>

<DataFormat>uri</DataFormat>

<DataFormat>bitmap</DataFormat> <DataFormat>html</DataFormat>

</ShareTarget>

</Extension>

</Extensions>

Declaring share contract in app’s manifest

//Step 2: Handle app activation

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) { //Step 3: Handle share operation shareOperation = eventObject.detail.shareOperation; if (shareOperation.data.contains(

Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {

shareOperation.data.getTextAsync().done(function (text) {

displayContent ("Text: ", text, false); }); }

//Step 4: Return a QuickLink object (Optional) var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink(); quickLink.id = “uniqueId”; quickLink.title = “Title for this link” ; quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri]);

//Step 5: Report extended status and completion shareOperation.reportCompleted(quickLink);

}

Implementing share target

Implementing share target

Code walk-through

Sharing tips:

SourceInclude as many data formats as appropriate

Leverage app’s context

TargetLeverage the Visual Studio template

Build a beautiful, lightweight share experience

Report completion & progress

Return QuickLinks

You can use Visual Studio to debug Share operations

Answers to share FAQs

1You can’t control what apps you share with. You can control the formats.

You can configure metadata from a website on share.

2No extra work required for long-running share operations

Look into BackgroundUploader class if you want to transfer the file during share

3Quicklinks are not roamed and they are not preconfigured.

QuickLink image can (and should) be different from your app icon

Search contract

Search contract makes your app searchable from anywhere in the system.

Search anatomy

1. Search box (scoped)

2. Apps that implement search contract

3. Query suggestions provided by foreground app

4. Result suggestions

4

1

3

2

//Step 1: Declare search in the manifest

//Step 2: Check app activation and implement actual search

WinJS.Application.addEventListener("activated", function (args) { /*.. */

if (args.detail.kind === appModel.Activation.ActivationKind.search)

return nav.navigate(searchPageURI, { queryText: args.detail.queryText }); }

// Step 3: Implement querysubmitted handler

Windows.ApplicationModel;.Search.SearchPane.getForCurrentView().onquerysubmitted = function (args) { nav.navigate(searchPageURI, args); };

//Step 4: [Recommended] Implement Suggestions Requested

appModel.Search.SearchPane.getForCurrentView().onsuggestionsrequested = function (eventObject) {

var text = eventObject.queryText.toLowerCase(); var terms = ["salt", "pepper", "water", "sugar", "oil"];

terms.forEach(function (term) {

if (term.indexOf(text) == 0)

eventObject.request.searchSuggestionCollection.appendQuerySuggestion(term);

});};

Implementing search

Implementing search

Code walk-through

Search tips: If your app implements search, use the charm

Implement a great results page with filter, sort, etc.

Avoid presenting results on the right edge

Provide suggestions

Use placeholder text

Search is not “Find”

Answers to search FAQs

1End-user is in control of the search pane.

Most frequently used searchpane goes to the top

User can turn apps search off in some apps

2You can have separators within results and create headers with these

3Suggestions can be asynchronous

There is a limit of five search suggestions

File Picker contracts

File picker contracts enable seamless integration between apps through the system’s file picking experience

FileOpenPickerCalling app File Picker

Providing app (implements contract)

Calls FileOpenPicker Loads default (last) store

User selects app to provide files

Loads app’s page to display provided files

Activated to provide files

User picks file (or save location)

Navigates to a page that displays files

Completes async calls and captures picked file

Returns picked file to calling app

//Step 1: Declare File Open Picker in manifest

//Step 2: Check app activation and implement file Open

app.onactivated = function activated(args) {

if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.fileOpenPicker) { // Step 3: Connect to the basket

pickerUI = args.detail.fileOpenPickerUI; pickerUI.onfileremoved = fileRemovedFromPickerUI;

//Step 3: Populate basket

args.setPromise(WinJS.UI.processAll() .then(function () { var listView = document.querySelector(".pickerlist").winControl; listView.itemDataSource = getPickerDataSource(); listView.onselectionchanged = updatePickerUI;

})); }}

// Step 4: Add/Remove from basket function updatePickerUI (args){

// .. get filename from listView selected items … Windows.ApplicationModel.Package.current.installedLocation.getFileAsync(fileName).then(function (file) { pickerUI.addFile(file.name, file); }); }

Implementing File Open Picker

Implementing file pickers

Code walk-through

File pickers tipsSupport as many file types as you can

Implement only the right contract, you don’t have to do both

Use deferred when needed

Create dedicated, light, picker UI with app’s context

Set appropriate view mode (e.g., thumbnail or list)

Have commit button on your task

Ensure user gets a visual confirmation

Answers to file picker FAQs

1App selection is matched to supported file types

2Apps are not subject to PLM during picking

3There is no event or notification to the target about a successful file saving operation

4The color from the picker is your app’s color

Contracts cheat-sheet Contract Manifest Activation VS

templateJumpstart

Share source No No N/N Windows.ApplicationModel.DataTransfer.DataTransferManager

Share target Yes Yes Yes Windows.ApplicationModel.DataTransfer.ShareTarget

Search Yes Yes Yes Windows.ApplicationModel.Search

File Open Yes Yes Yes Windows.Storage.Pickers.Provider.FileOpenPickerUI

File Save Yes Yes No Windows.Storage.Pickers.Provider.FileSavePickerUI

Settings No No N/N Windows.UI.ApplicationSettings.SettingsPane

PlayTo Yes No N/N Windows.Media.PlayTo.PlayToManager

Cached file updater

Yes Yes N/N Windows.Storage.Provider.CachedFileUpdaterUI

Recap

More integration points: extensions

Account picture providerBackground tasks Camera settings Contact pickerFile activation Game explorer Print task Protocol activation

References

SamplesApp Settings ContractFile PickerSearchPrintShare sourceShare targetPlayTo

Design guidelinesSharingFile pickersSearchAppSettings PlayTo

• Develop: http://msdn.microsoft.com/en-US/windows/apps/br229512

• Design: http://design.windows.com/

• Samples: http://code.msdn.microsoft.com/windowsapps/Windows-8-Modern-Style-App-Samples

• Videos: http://channel9.msdn.com/Windows

Resources

Please submit session evals by using the Build Windows 8 appor at http://aka.ms/BuildSessions

© 2012 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.