Windows 8 Contracts and Extensions: Search Part-1

Don't re-invent the wheel when building your Windows 8 apps. Instead, save coding time by using (and customizing) the Search contract to add this critical piece of functionality.

• GET CODE DOWNLOAD

As a Windows Store app developer, knowing the ins and outs of the contracts and extensions in Windows 8 is paramount.

Contracts and extensions play a major role in Windows Store app development. Not only do they provide out-of-the-box support for many of the common operations needed within an app, but in many cases they're the only way to interact with Windows, other apps or the device itself. Often, the first thing that comes to mind when you think of contracts and extensions is the charm bar. Within the charm bar, the Search contract tends to be the logical starting point. This article will explore the Search contract and demonstrate how to effectively integrate it into your Windows Store apps.

Search in a Windows Store App
The ability to search is a common feature in many apps. It's a good bet that if your app includes any sizable amounts of data, the user is going to want the ability to search through it. Fortunately, most search implementations have the same two requirements: the ability to enter a search term and a way to display the results. Windows 8 provides a unified approach for apps to surface this functionality to their users.

The most obvious advantage of using the Search contract is the ability to reuse the code that has already been written for you. This includes things like an interface for entering a search query, a way of storing previous searches and exposing suggested queries. In addition, the Search contract exposes several customization points that can be used to provide a more targeted approach for your users.

One of the five Microsoft design language principles is "win as one." While the principle covers a lot of territory, one aspect of it is to use familiar features. If a user is familiar with searching other Windows Store apps by using the Search charm, and therefore the Search contract, the user will already be familiar with how to search your app if you implement the same contract. This eases the learning curve for a user when he first opens your app, and it will go a long way toward improving customer retention.

Adding the Search Contract to Your App
There are three things that your app must have in order to successfully implement the Search contract. First is the addition of a search declaration in the app's appxmanifest. This can be accomplished by adding a search declaration in the Declarations tab of the appxmanifest designer. The declaration can also be directly added to the XML in the appxmanifest by adding an Extension node to the Extensions collection in the Application node:

<Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="VSMSearchSample.App">
  <VisualElements DisplayName="VSMSearchSample" Logo="Assets\search150.png" 
                  SmallLogo="Assets\SmallLogo.png" Description="VSMSearchSample" 
                  ForegroundText="light" BackgroundColor="#0072c6">
    <DefaultTile ShowName="allLogos" />
    <SplashScreen Image="Assets\searchSplash.png" />
  </VisualElements>
  <Extensions>
    <Extension Category="windows.search" />
  </Extensions>
</Application>

The next step is to enable your app to handle being activated by the Search contract. When a user enters search criteria in the search screen, your app is launched within the search results window. Your app will be notified when the app is being launched from a search query. When building a XAML-based Windows Store app, this is done by calling the OnSearchActivated method within the App class. To successfully be notified when the app's being activated by search, add an override to the default method as shown in Listing 1.

Listing 1. Implementation of OnSearchActivated. 

protected override void OnSearchActivated(SearchActivatedEventArgs args)
{
  Frame rootFrame = Window.Current.Content as Frame;

  // Do not repeat app initialization when the Window already has content,
  // just ensure that the window is active.
  if (rootFrame == null)
  {
    // Create a Frame to act as the navigation context and 
    // navigate to the first page.
    rootFrame = new Frame();

    // Place the frame in the current Window.
    Window.Current.Content = rootFrame;
  }

  if (!rootFrame.Navigate(typeof(SearchPage), args.QueryText))
  {
    throw new Exception("Failed to create initial page");
  }

  // Ensure the current window is active.
  Window.Current.Activate();
}

The OnSearchActivated method receives a single parameter, SearchActivatedEventArgs, which contains information about the activation and the query. The query text entered by the user is passed in the QueryText property.

The final thing to add is the UI showing the results. In a XAML app, this is typically a Page to which the app will navigate to help preserve the navigation stack. Once these three things have been added to your app, you can successfully implement the search contract.

The solution available to download with this article is a demo app that allows the user to explore a subset of sessions available at TechEd North America 2013. As seen in Figure 1, the user can drill down to the session details from navigating through the categories or the presenters. In an app like this, search is an obvious benefit. I added a basic search page by implementing these three requirements; it's shown in Figure 2.

[Click on image for larger view.]Figure 1. Drill down to session details by navigating through categories or presenters.

[Click on image for larger view.]Figure 2. A basic search page.

Adding Search from Visual Studio
Before digging into the Search contract any further, it's important to mention a second approach to implementing the Search contract in your app. While the three requirements can all be added to your app manually, Visual Studio provides a templated solution for adding search to your app, which also contains a few extra goodies. Visual Studio includes a Search Contract template that will add the necessary pieces to your app. The Search Contract template is available for both XAML and JavaScript Window Store apps. To add the Search Contract to your app, right-click the project node in the Solution Explorer, then select Add | New Item. In the item list, there's a Search Contract, as shown in Figure 3. In a XAML app, the name should be the name you want to give the page that returns the search results.

[Click on image for larger view.]Figure 3. The Search Contract in Visual Studio.

When adding the contract to your app, the template adds a search declaration to your appxmanifest, an override of the OnSearchActivated method in the App class, and a new search page to your solution. Depending on which project template you began your solution with, you may also find that several additional supporting files have been added to your project. These include some value converters, a layout-aware page that the new search page inherits from, and a suspension manager.

The search page created provides an example of how to fully implement a search page, including default templates that provide the same look and feel that the Grid and Split App project templates use. Depending on the structure of your app, using the template approach can sometimes add more work than benefit. However, regardless of whether you use the search contract template in your project or not, it's worth adding it to a sample project just to get an understanding of how to approach the implementation.

Designing a Search Page
When implementing a search page in your app, first get the search page loaded and pass the query text to it. Listing 1 takes the QueryText property of the SearchActivatedEventArgs and uses the main Frame object to navigate to the search page, passing the QueryText as the parameter. The OnNavigatedTo method of the Page object exposes the query information and can use that to update a view model for the page. A single view model is used in the demo application for simplification. The following code shows the override of the OnNavigatedTo method of the SearchPage:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
  var searchText = e.Parameter.ToString();

  App.ViewModel.SearchFilter = ViewModels.SearchFilterType.All;
  App.ViewModel.Search(searchText);
            
  itemGridView.ItemsSource = App.ViewModel.SearchResults;
  tbQuery.Text = searchText;

}

A search page should contain certain information. First and foremost, the search results should be shown in some format. Most Windows Store apps will implement this by using a GridView; however, the results should be shown in a way that makes sense for your app.

The second important piece of information is the query text itself. By displaying the entered query text on the search screen, the user is given verification that the app is searching for the correct term. This is especially important when no results match the query.

An additional piece of beneficial information is the number of results returned. This tells the user if he needs to narrow the results by providing a more detailed search query. You can also use this number to inform the user if your app is limiting the result set to a certain number of results. For instance, the app could display a message informing the user that the results have been maxed out. Refer back to Figure 2 for an example of the basic search page layout.

The next feature that's commonly found in search pages is the ability to filter the scope of the search. The demo returns several types of data: categories, presenters and sessions. By adding a filter to the page, the user can fine-tune his search beyond a simple text search.Figure 4 shows the search screen with a dropdown filter added. The filter for the search page can be as simple or as complex as your data demands.

windows 8 windows 8 development 19:38