[This topic is featured in Develop great apps for Windows 8.]
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 You can use shortcut keys to access charms, including the Search charm. The Windows Logo Key + C lets you select any of the charms, and the Windows Logo Key + Q selects the Search charm.
You can use tools in Microsoft Visual Studio Express 2012 for Windows 8 to add search to your app, via the Search contract, 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 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
Add the Search contract from the Add a New Item dialog, by selecting Search Contract from the center pane of the Add a New Item dialog. Then click the Add button.
To learn more about using Microsoft Visual Studio's Search Contract to add search, see Adding a Search Contract item template.
Warning If you created your app using the Blank App or Fixed Layout App template you also need to add navigation support to your app in order to get search to work. You can support navigation the same way that the Grid, Split, and Navigation App templates do by adding a custom control called PageControlNavigator to your app. You can see how this custom control supports navigation in Quickstart: Using single-page navigation. If you'd rather support navigation without using a custom control, you have to write your own code that listens for and responds to navigation events like WinJS.Navigation.navigated. You can see an example of how to support navigation without using a custom control like PageControlNavigator in the Navigation and navigation history sample.
What the tools do to help you 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 that Visual Studio creates, 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.
Respond to a search query when your app is not the main app on screen.
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. This ensures that your users will have a positive experience when they search your app.
Add filters to your page
The app creates filters that are shown on the search results page, so that the user can refine their query. Replace the default filters with filters that make sense for your app, or remove them entirely if they don't make sense for your app. The filters are created in the
Populate your page with results from your app's data
The app uses the
searchDatafunction to search its data, and returns a WinJS.Binding.list of results to display in the app's search results page. You should update this function to bind your search results to the list view control by using WinJS.Binding.list to represent your results (instead of relying on placeholder data). The
For design guidelines for your search results page, see Guidelines and checklist for search.
To learn more about how to work with data in Visual Studio templates, see Adding data to a project template.
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 to check the queryText. This handler was added automatically by Visual Studio.To 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
The search box displays search suggestions in the search pane. You should add suggestions because they save users' time and give important 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, by using only a few lines of code. Alternatively, you can register for the suggestionsrequested event and build your own list of suggestions. These are suggestions that you retrieved from another source, like a locally-defined list or a web service.
For code examples that show you how to add search suggestions, download the Search contract sample. The sample demonstrates how to add search suggestions using all three possible sources, and how to add suggestions for East Asian languages using an Input Method Editor (IME).
Enable users to type into the search box directly from your app
You should consider giving 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. When this setting is enabled on a page, the search pane opens as soon as the user starts typing and the search box is immediately populated with what the user is typing.
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 type 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. The template and associated styles are defined in searchResults.html and searchResults.css.
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 add code to the
You can learn more about basic navigation in Quickstart: Using single-page navigation.
You should test your app's integration with the Search contract by using the Search charm. Test your app in each of the following circumstances, with at least these two test queries:
- 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 and switch to the start screen before you open the Search charm and enter each query.
- Perform test searches while your app is snapped. Launch your app and snap it, making sure your app stays on its home page before you 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
- 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: 11/29/2012