Implementing Contracts

Early in the chapter, we discussed interaction with charms on the start bar. Those interactions are handled in your app by implementing the appropriate contracts. There are several contracts your app can implement, with Search and Share being the most important.

Saying that a contract is “implemented” sounds like implementing an abstract interface, but in fact many contracts are implemented merely by taking two steps:

Let's step through a very simple case for working with the Search charm. This is by no means a full search implementation; it just shows the minimum code to detect when a Search has been requested and then do something in the UI.

First, start a new app with the Blank App template, and name it SearchContractExample.

To declare support for the Search contract, open the Package.appmanifest item in the project and go to the Declarations tab. It has a drop-down for the various declarations, and the Search contract is in the list. Figure 13.23 shows the Declarations page, with the list of available declarations dropped down.

Figure 13.23 The Package.appmanifest Declarations page, showing the drop-down of declarations. The Search contract declaration is selected in the drop-down.

To declare support for a Search contract, just select Search in the list and then press the Add button. Some properties will come up on the right side in case you want your app to delegate the searching to another app. To do searching within your app, you can ignore those properties.

Then you need to handle the associated event for searching at the application level. In the code behind for App.xaml, place the following sub (code file: SearchContract.vb):

Protected Overrides Sub OnSearchActivated(args As SearchActivatedEventArgs)

    ' Carry out search operations here
    ' and display results somewhere in the app.
    ' You might use LINQ or other techniques to find records
    ' that match args.QueryText.

    ' In this demo version, I'm just passing the search
    ' query string to the main page of the app.

    Dim pg As MainPage
    pg = CType(CType(Window.Current.Content, Frame).Content, MainPage)

    ' Search query text is available in args.QueryText
    pg.DisplaySearchResults(args.QueryText)

End Sub

Finally, place a TextBlock somewhere in MainPage.xaml with the Name set to SearchResultsTextBox. Then place the DisplaySearchResults method referenced above in the code-behind for MainPage.xaml:

Public Sub DisplaySearchResults(sQueryString As String)
    SearchResultsTextBox.Text = "Search activated with query string " & 
sQueryString
End Sub

This is enough to show that the search operation is active in the app. Run the app, swipe the charms bar into place, and select the Search charm. Put in a search query string, and press the search button. You should see the TextBlock update with the search query string you entered.

How you actually carry out the search operation in your application is up to you. Typically, you would either carry out a database query, or use LINQ to query against data you have already fetched.

Updating views directly from the App.xaml code behind is not a good practice in general. This example is just to show you the basics. If you intend to handle searching, a good pattern for your code is to have a property on your data model or viewmodel that holds search results. Then you can bind an appropriate element to that property. That way, the App.xaml does not need to know where the search results are displayed. It needs only to update the model.