I have looked into some videos and MSDN articles about the Search Contract and created a cleaner MVVM example without using the Visual Studio template for Search Contracts. The result is a fully working app also showing concepts like Search suggestions, Converters, Horizontal Listbox, XAML Resources, Blendability and INotifyPropertyChanged injection without becoming complex. Source code is included.
Overview
The Demo App lists Terry Pratchetts wonderful books about the Discworld.
The Discworld is a flat planet carried on the backs of four giant elephants – Berilia, Tubul, Great T’Phon and Jerakeen – which in turn stand upon the pock-marked shell of the star turtle Great A’Tuin. It exists right on the edge of Reality, and as such ‘the least little thing can break through from the other side’.
It contains three pages:
StartPage: Welcoming page.
BookPage: Lists book series and book details.
SearchResultPage: Shows a list of book matching a search query.
It is built as a one project Visual Studio 2012 solution with the following structure:
and have this code dependency graph:
It is using the Fody and PropertyChanged.Fody NuGet packages for automagically injecting INotifyPropertyChanged code into properties. If you are new to NuGet, watch this YouTube video: How do you install a NuGet package in Visual Studio 2012?
StartPage – MVVM
The StartPage let the user tap on “Show all books” or one of the three featured books. Both choices will lead to the BookPage. But let us stay on the StartPage while looking into how I used the MVVM pattern in this app.
The StartPage XAML defines it’s datacontext as the StartPageVm (ViewModel).
The StartPageVm expose a property named FeaturedBooks
and fills it with BookVmi (ViewModelItems) in its Init() method:
The StartPage XAML finally databinds the ListBox showing featured Books to the StartPageVm property:
Fody
The ViewModels have a base class, VmBase, which implements the INotifyPropertyChanged interface. This will trigger the extension Fody and its plugin PropertyChanged.Fody to inject PropertyChanged code into the ViewModels properties. This leads to a much more readable source code and saves the developer from writing repetitive code.
StartPage – Blendability
Blendability is about how to enable designers to see the correct preview of their Views in Visual Studio and/or Expression Blend. The image above shows how the StartPage looks like in Blend. You (or your designer if you are lucky and have one) will appreciate to have sample data when creating the UI.
One way to achieve this is by generating sample data from inside Blend. It works mostly but I have had some problems with maintaining the sample data and prefer to create the sample data in the ViewModel.
BookPage – Horizontal ListBox
The BookPage let the user select a book from the horizontal ListBox and shows details about it above. This is how to make a ListBox show its items horizontal:
SearchResultPage – Converters
We are now closing in on the real topic for this post. The SearchResultPage will show books with titles or descriptions containing the search query. It will also group the books by book series at the top of the page. This grouping is called filtering in the MSDN example.
Value Converters can be used to convert databinded data to something better suited for the UI. Most things can probably be done in the ViewModel and Converters might have a performance penalty. But they are quite nifty encapsulated functions.
As an example the SearchResultPage use a converter named ListEmptyToVisibilityConverter. It helps to decide if the “No results match your search”-text or the search result grids will be visible.
You create a converter by implementing the IValueConverter interface:
Theme Folder – XAML Resources
The final topic before starting with the Search Contract is XAML Resources. I have extracted all edited XAML templates to AppStyles.xaml, all brushes to Brushes.xaml, colors to Colors.xaml and text styles to TextStyles.xaml. I recommend to have it this way instead of hard coding all colors into the pages.
Dictionaries are merged by adding a ResourceDictionary to the generic collection referenced by MergedDictionaries. This can be done in App.xaml:
And this is how you will reach the brushes in Blend:
Search Contract
When you add the Search Contract, users can search your app from anywhere in their system by selecting the Search charm. The rest of the post will now show how to implement this and also how to add search suggestions under the search box in the search pane.
You can read more about the Search Contract here: Quickstart – Adding search to an app (Windows Store apps using C#/VB/C++ and XAML) , Windows Store apps for Absolute Beginners with C#, Part 20: Implementing the Search Contract and 31 days of Windows 8 day 6 Search Contract.
Declare the Search contract in the app manifest
Declare the Search contract in the app manifest by adding its declaration.
Respond to a search queries
Override the OnSearchActivated method in App.xaml.cs and fetch the query string from the SearchActivatedEventArgs. Pass this to the SearchResultPage.
Implement View, ViewModel and ViewModelItems for SearchResults
The SearchResultPage will receive the query string in the LoadState method. It will forward it to the ViewModels Search method:
The SearchResultPageVm will find all books matching the search query and group them in series (Filter). The app will only show series with at least one book in it. The Search method will finally set the properties the view is databinded to.
Each Filter will have a name, a list of books and an active flag.
The view SearchResultPage will finally bind its UI to the ViewModel to make the search feature work.
Add search suggestions
Search suggestions are displayed under the search box in the search pane. This demo app will give suggestions on all the book titles matching what the user actively is typing in the search box.
Register for the SuggestionsRequested event in the App.xaml.cs OnLaunched method. This is also a good place to fetch all keywords to use later when the event is handled.
The App_SuggestionsRequested method will handle the event by obtaining suggestions and populating the SearchSuggestionCollection based on the user’s SearchPaneSuggestionsRequestedEventArgs.QueryText.
Great :) The app user will now both be able to use the search pane and also have search suggestions!
Summary
I have described how to create a simple MVVM Windows Store App and implement the Search Contract without using the Visual Studio template to keep the code as clean as possible. Please note that this is not a complete or performance optimized app even if it has some more code parts implemented than a normal feature demo
The book info is from the http://discworld.wikia.com licensed under the Creative Commons Attribution-Share Alike License.
You can download the entire sample solution here:
/Johan
codeblog.silfversparre.com