Windows 8: Be a good sharing citizen

Note: Code samples are WinJS

I’ve been working with Windows 8 and building Windows Store Apps more and more. Building native Windows Apps with HTML/JS/CSS is, in a word, awesome. I’ve mentioned before how the OS is a first class citizen in the development space. Having standard API’s in the dev environment to handle common tasks like searching and sharing is another nice feature in Windows 8 Development. I wanted to take a quick moment to talk about the sharing contract. You can download a full working example of how to implement the sharing contract here.

This example does a great job of dealing with situations where you can and want to share. But what about times when sharing is not appropriate? A good user experience means the user not having to guess as to whether encountered functionality is intended or a bug. By default, when the share contract is not implemented you get a pretty blunt message back: “This app can’t share.”

Looks pretty, but it’s not all that informative.  Fortunately, it’s very simple to provide your users with enough information so they know what they see is what you, as the app developer intended. The following code is a basic and typical share contract data request function:

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

        // Title is required
        var dataPackageTitle = document.querySelector("article .item-title").textContent
        if ((typeof dataPackageTitle === "string") && (dataPackageTitle !== "")) {
            var dataPackageText = document.querySelector("article .item-content").innerHTML
            if ((typeof dataPackageText === "string") && (dataPackageText !== "")) {
                request.data.properties.title = dataPackageTitle;
                request.data.setText(dataPackageText);
            } else {
                request.failWithDisplayText("A problem occurred with this sharing request");
            }
        } else {
            request.failWithDisplayText("A problem occurred with this sharing request");
        }
    }

This still doesn’t do everything we need. For example, using the Grid Template as an example, this code would only work on the item detail page. If you happen to invoke the Share Contract from the Group Items or Group Details page, you will either get an error or the necessary data won’t be found. In most cases, it’s an individual item you are looking to share.  With that in mind, consider adding code like this to your common share data request function:

if (WinJS.Navigation.history.current.location != "/pages/itemDetail/itemDetail.html") {
   request.failWithDisplayText("Please note, you must navigate to an individual item in order to share.");
   return;
}

Now, when the user wants to share something in a context that does not account for that functionality, the user will know two things:
1. It’s not intended to be used in this context and;
2. The user knows where the sharing context is

This yields much better results: