In this post, I will show how simple it is to add a search contract to a Windows 8 Store app. This contract allows the user to search within your application from anywhere in Windows 8 using the search charm.  We will use my Calibre frontend app to show this. Check this video to see the raw action of what we are making.

This is the second post of my quest to writing a Windows 8 Store app for Calibre. The previous post can be found here.

Adding a search contract

There are two ways of adding a search contract to your application:

1. Manually (good explanations here and here)
2. Automatically: letting Visual Studio to the plumbing

Of course, we are going for option 2. To do this, we perform the steps described here:

1. Open the Add a New Item dialog. You can open this dialog in several ways:
   1. By clicking the Project > Add New Item… menu option
   2. By clicking the Add > New Item… menu option from the project’s context menu
   3. By using the Crtl + Shift + A keyboard shortcut
   4. To add the Search contract from the Add a New Item dialog, select Search Contract from the centre pane of the Add a New Item dialog. Then click the Add button.

Visual Studio will then add Search to the supported declarations of your application (check for yourself in the  Package.appxmanifest  > Declaration) and create a search results-page where the search results will be displayed (xaml+cs). If you now run your application and click the search charm anywhere in Windows 8, you’ll already see your application listed. In fact, if you now search and choose your app you’ll be transported to the newly created, empty, search page.

Responding to the search query

Finding your way around the code of the newly created search results-page might be a bit daunting at first. However, we will ignore the filtering for now and simply respond to any search query by starting a new search in our Calibre database. Three things need to be done:

1. Save the query string inside the ViewModel of the search page
2. Perform the search on our database
3. Change the XAML-view to show the results (books)

Save query string in the ViewModel

First up, when a search query is started we enter the search results-page through the LoadState() method. In here additional filters (e.g. categories) can be defined. We’ll only use this method to save the received query string (line 1).

            this.DefaultViewModel["Query"] = queryText;
            this.DefaultViewModel["QueryText"] = '\u201c' + queryText + '\u201d';
            this.DefaultViewModel["Filters"] = filterList;
            this.DefaultViewModel["ShowFilters"] = filterList.Count > 1;

Note1: It is important to add this line BEFORE line 3 as this third line will fire the “Filter_SelectionChanged()” method because the Filters-field was changed. Note2: The QueryText field is used to show the query string in the header of the UI (hence the addition of quotes to make it visually more clear).

Perform the search on our database

In the Filter_SelectionChanged()-method we will query the Calibre-database. The template is kind enough to point out that we just have to add an ICollection to DefaultViewModel[“Results”] and we’re ready. First, we make this method async  and then we add :

                object query;
                if (this.DefaultViewModel.TryGetValue("Query", out query))
                {
                    var result = await CalibreDal.LoadCalibreDatabaseAsync("metadata.db");
                    this.DefaultViewModel["Results"] = (from p in result where p.Author.ToLower().Contains(query.ToString()) select p).ToList() ;
                }

Right before:

// Ensure results are found
object results;
ICollection resultsCollection;

So in this example, I first load the CalibreDatabase on line 4. Next up, we look for any book containing the query string in the author-field and feed that result to the “Results”-field of the ViewModel.

Change the XAML-view

To sexify things (yes, that’s a word I once heard someone speak out loud) we go the SearchResultsPage.xaml. The resultsGridView is the grid that will show our results (duh!). So we point the ItemTemplate to the bookTemplate used in the main program, et voila:

                <GridView
                    x:Name="resultsGridView"
                    <!-- etc -->
                    ItemTemplate="{StaticResource bookTemplate}">

Note: Though not explained here, remember to also change the resultsListView template as this will be the template used when the application is snapped.

Conclusion

I briefly showed the steps to follow to have a basic, but workable search-contract in your application. We use the build-in search-contract template to show how straight-forward this is.