Continuing with Part 8 of building WinRT applications with HTML and JavaScript.  You can find earlier installments at their respective links: Part 1 – Part 2 -  Part 3- Part 4- Part 5- Part 6- Part 7. If you are interested in the source code for the TweetScan application, you can get it off of GitHub.  Make sure you sign up for How to develop a Windows 8 app in 30 days from Generation App.

Watch video here

The Search contract is a way you can integrate the Windows 8 search experience into your game. Windows 8 provides a Search feature that is enabled via the Charm bar (shown at right). The Charm bar is activated by a user swiping from the right edge of the screen with a finger, or by either a mouse or keyboard action (mouse to the upper right corner of the screen or Windows+C ). From the Charm bar, the user can select the Search charm and enter the default Search experience

When dealing with Search, we have two ways of integrating.  The first is accepting a query request while our application is running, and the second is dealing with the user launching our application as part of a query request (i..e, picking our app after typing in a query in the Search Pane).  Let’s take a look at how we handle the first scenario in TweetScan.

I won’t cover it here, but the first step was to move the WinJS.xhr request into its on search(tag) function.  The Twitter search Uri was changed to insert whatever tag value was passed to our function in place of the previously hard-coded Windows8 hashtag.  With a search function in place, we need to handle a query submitted request from the Search pane.

var searchPane = Windows.ApplicationModel.Search.SearchPane.getForCurrentView();
searchPane.onquerysubmitted = function (e) { search(e.queryText); };

That’s it.  We capture the querysubmitted event and pass the query text entered by the user to our search() function.  In our case, we update the same page that is currently being displayed.  In your app, you may with to navigate to a dedicated search results page via call like nav.navigate(“/searchresults.html”,e.queryText).  How you resposd to the querysubmitted event is up to you.

I am not doing it in TweetScan, but you can also handle the suggestionrequested event which allows you to feed real-time suggestions after each key stroke the user enters in the Search pane.  Check out the Search Contract Sample app for examples on how to do that.

If the user launches our application from the Search pane, we can detect that in our default.js page in the Application’s activated event handler.

app.addEventListener("activated", function (args) {
        if (args.detail.kind === activation.ActivationKind.launch || 
            args.detail.kind === activation.ActivationKind.search) {
...
}};

I just handled everything the same – launch vs. search.  In your app, you will more than likely have different code paths for each ActivationKind.  When the code reaches the point where it is time to navigate to home.html, I make a simple check to see if why TweetScan was launched and navigate appropriately:

if (args.detail.kind === activation.ActivationKind.search)
      return nav.navigate(Application.navigator.home, args.detail);
else
      return nav.navigate(Application.navigator.home);

If TweetScan was launched because of search, I still navigate to home.html, but I also pass along the search arguments.  In home.js, I now need to determine if there is a search term or not.  If there is, I will pass that tag to the search function instead of the Windows8 default.

ready: function (element, options) {

            if (tag === undefined)
                tag = "Windows8";

            if (options && options.queryText)
                tag = options.queryText;

            search(tag);
}

There ya go.