Quickstart: Adding search to an app (Windows Store apps using C#/VB/C++ and XAML)
Let users search your Windows Store app by adding the Search contract. When you add the Search contract, users can search your app from anywhere in their system by selecting the Search charm.
Tip Users can use shortcut keys to access charms, including the Search charm. The Windows Logo Key + C lets the user select any of the charms, and the Windows Logo Key + Q selects the Search charm.
All Windows Store apps have access to tools in Microsoft Visual Studio Express 2012 for Windows 8. You can use these to successfully add search to your app and adhere to the UX guidelines for search. See Guidelines and checklist for search to learn more.
Open your project in Visual Studio Express 2012 for Windows 8 and follow these steps to use the tools to add search to your app:
- Open the Add a New Item dialog.
You can open this dialog several ways:
- By clicking the Project > Add New Item... menu option
- By clicking the Add > New Item... menu option from the project's context menu
- By using the Crtl + Shift + A keyboard shortcut
To add the Search contract from the Add a New Item dialog, select Search Contract from the center pane of the Add a New Item dialog. Then click the Add button.
You can learn more about using Microsoft Visual Studio templates in Templates to speed up your app development.
Here is how the tools help you to fulfill the minimum requirements of the Search contract:
Declare the Search contract in the app manifest.
You can see that the contract was added by clicking on the manifest file in your Visual Studio project and selecting the Declarations tab.
Create a basic search results page for your app.
The search results page, which is created automatically by Visual Studio, adheres to the UX guidelines for results pages in Guidelines and checklist for search.
Respond to a search query while your app is the main app on screen.
When the user searches your app while it is the main app on screen, the system fires a QuerySubmitted event. The Visual Studio tools (globally) register a handler that responds whenever this event fires. The handler then shows your app's search results page for the user's query.
Respond to a search query when your app is not the main app on screen.
When the user searches your app while it is not the main app on screen, the system fires an Activated event and stores the arguments for this event by using SearchActivatedEventArgs. The Visual Studio tools add code to override the OnSearchActivated method. Your app can then respond to this event by showing its search results page for the user's query. This code is added in the App.xaml.cs file.
You can learn more about activating your app in How to activate an app.
Visual Studio added a basic search results page and fulfilled the minimum requirements of the Search contract automatically. However, you still need to take the following steps to ensure that your app is completely integrated, and that your users will have a positive experience when they search your app.
Add filters to your page
By default no filters are shown on your search results page. You should add filters that make sense for your app and users, by adding code to the
LoadStatemethod. The method is commented to help make implementation easier.
Populate your page with results from your app's data
To use the query text and current filter to populate your page with results, you should add code to the
Filter_SelectionChangedmethod in the search result page code (SearchResultsPage.xaml.cs by default). You can access the query text from the
DefaultViewModelobject. This is where the
LoadStatemethod stores query text (in quotes) by default. The
Filter_SelectionChangedis commented to help make implementation easier.
Handle activation for empty search queries
Users may select your app from the Search charm without entering query text. They may do this to scope their search to your app, or simply as a quick way to get back to what they were last looking at. Your app should anticipate the user's needs and respond differently in each case.
Add code to your app's search-activated event handler that checks the QueryText. This handler was added automatically by Visual Studio. Then, to help determine which app page is best to display when your app is activated and QueryText is empty, use the following logic:
- When your app is launched for the first time, display your app's home page.
- If your app is suspended or running in the background, display your app's current page.
- Otherwise, display a generic search landing page.
Add search suggestions
Search suggestions are displayed under the search box in the search pane. Suggestions are important because they save users' time and give valuable hints about the kinds of things users can search for in your app.
You can get suggestions from several sources:
- You can define them yourself. For example, you could create a list of car manufacturers.
- You can get them from Windows if your app searches local files.
- You can get them from a web service or server.
For user experience guidelines about displaying suggestions in the search pane, see Guidelines and checklist for search.
You can use LocalContentSuggestionSettings to add suggestions, based on local files from Windows, in only a few lines of code. Alternatively, you can register for the SuggestionsRequested event and build your own list of suggestions that is made up of suggestions you retrieved from another source (like a locally-defined list or a web service).
For code examples that show how to add search suggestions, download the Search contract sample. The sample demonstrates how to add search suggestions by using all three possible sources, and how to add suggestions for East Asian languages by using an Input Method Editor (IME).
Enable users to type into the search box directly from your app
You should give your users the ability to search for content in your app by simply beginning to type with their keyboard.
Many people will use a keyboard to interact with Windows 8. Letting users search by typing makes efficient use of keyboard interaction and makes your app's search experience consistent with the Start screen.
Use SearchPane.ShowOnKeyboardInput so that the search box receives input when a user types. Enable ShowOnKeyboardInput on your app's main page and on search results pages, so that users can search your app quickly and consistently. For user experience guidelines about using typing to search in your app, see Guidelines and checklist for search.
If needed, customize the look of search results
The search results page defines an item template that displays a small image, with adjacent title and properties, for each result. By default, the template and associated styles are defined in Common/StandardStyles.xaml.
If the default item template doesn't suit your search results, you should update it by copying the item template locally, and then modify it. You can learn more about ListView and GridView item templates in Item templates for grid layouts and Item templates for list layouts.
If needed, add navigation to a result's details page
If you want to display detailed information about a result that the user selected, you should create an app page specifically to display this information and navigate to that page when a result is selected. You should register an event handler for the ItemClick event on both ListView and GridView (you can use a single handler). Then your app can navigate to the result detail page when it is the main app on screen and when it is snapped.
You can learn more about page navigation in Quickstart: Navigating between pages.
You should test your app's integration with the Search contract by using the Search charm to search your app in each of the following circumstances. Use at least these two test queries in each case:
- A query with search term(s) that you know should have search results
- An empty query
- Perform test searches while your app is the main app on screen. Launch your app, open the Search charm while that app is active, and enter each query.
- Perform test searches when your app is not the main app on screen. Launch your app, switch to the start screen, and then open the Search charm and enter each query.
- Perform test searches while your app is snapped. Launch your app and snap it, make sure your app stays on its home page, and then open the Search charm and enter each query.
- Perform test searches when your app is launched for the first time. Make sure your app is not running and is not suspended before you open the Search charm and enter each query.
You used the tools built into Visual Studio Express 2012 for Windows 8 to add search to your app. Now, users should be able to use the Search charm to search your app.
For guidelines to help you design and create a good search experience for your users, see Guidelines and checklist for search.
- How to activate an app
- Windows application contracts
- Roadmap for creating apps using C#, C++, or VB
- Guidelines and checklist for search
- Search contract sample
- Additional reference
- Windows.UI.WebUI.WebUIApplication.Activated event
- Windows.ApplicationModel.Activation.ActivationKind enum
- Windows.ApplicationModel.Activation.SearchActivatedEventArgs class
Build date: 10/26/2012