Monday, October 29, 2012

App Search and the Okra App Framework

One advantage of the Okra App Framework over other MVVM-based application frameworks is that it is designed from the ground up to work great with Windows 8. Over the next few versions this will become more evident as features are added to support the various Windows 8 system contracts – search, settings, sharing, etc.

In this post I will describe how the Okra App Framework makes it easy to add search to your application using the same MVVM principles that you are using for the rest of your application.

The Search Contract in Windows 8

When developing Windows Store applications many developers will want to take advantage of the Windows 8 search charm. This allows users to search across all applications from a single, consistent entry point. In order to add search functionality you would generally override the OnSearchActivated(…) method in the App.xaml.cs code-behind. In fact the standard Visual Studio search page template will add the code required to do this. For a great Windows Store application however you would want to,

  • Fully follow the Windows search design guidelines (available here)
  • Preserve the existing application state and correctly handle back navigation from the search page
  • Navigate to a suitable page (normally the application home page) if an empty search is performed
  • Improve performance by attaching to the SearchPane.QuerySubmitted event where possible
  • You may also want to implement the search page using the MVVM pattern

By simply using the Okra App Framework search manager it will take care of these requirements.

Adding Search to Your Application with the Okra App Framework

The Okra App Framework provides a search manager to handle the process of activating search in your application. This is represented by the ISearchManager interface,

public interface ISearchManager
{
    string SearchPageName { get; set; }
}

By default the SearchPageName property is set to null, and Okra will not handle search activation. To opt-in to the search integration you should set the page name for search in your application’s bootstrapper SetupServices() method.

public class AppBootstrapper : OkraBootstrapper
{
    protected override void SetupServices()
    {
        SearchManager.SearchPageName = "Search";
    }
}

By adding this single line your application has been enabled for search, and a page named “Search” will be navigated to when the user performs a search within your application (note that you will also need to declare that your application supports search in the application manifest).

Defining Your Search Page


Because search uses the standard Okra page discovery mechanisms you define your search page and view-model as you would any other page within your application,

[PageExport("Search")]
public sealed partial class SearchPage : LayoutAwarePage
{
    ...
}
 
[ViewModelExport("Search")]
public class SearchViewModel : NotifyPropertyChangedBase, ISearchPage
{
    ...
}

One thing to note is that the search view model implements the ISearchPage interface (this could also be implemented by the page if you are not using the MVVM pattern),

public interface ISearchPage
{
    void PerformQuery(string queryText, string language);
}


This method will be called whenever the page should show a new set of search results. In this method you provide the application logic to perform the search operation and display the results to the user. Note that this may be called multiple times for a single page as the user performs subsequent searches and you should refresh the content with the new results.

Summary


In the above discussion I have shown how the Okra App Framework makes it simple to implement search functionality in applications based on the MVVM pattern.

A sample search application is available from the Okra CodePlex downloads section. This is based on the Visual Studio search template, but modified to correctly implement the MVVM pattern.