Quickstart: Adding search to an app (Windows Store apps using JavaScript and HTML) (Windows)

Language: JavaScript and HTML | VB/C#/C++ and XAML

8 out of 18 rated this helpful - Rate this topic

In this article

Prerequisites
Use Microsoft Visual Studio tools to add search
Complete Search contract integration
Test your Search contract integration
Summary and next steps
Related topics

[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.

Prerequisites

None.

1. Use Microsoft Visual Studio tools to add search

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.
Associate your app's home page with the JavaScript code that Visual Studio added.

Copy the following <script> tag from the JavaScript file that Visual Studio added to your project. The tag is located in a comment near the top of the file. Paste the tag into the <head> tag of the HTML file for your app's home page. This page is Default.html by default.
HTML
Copy
<script src="/searchResults.js"></script>
By default the JavaScript file added by Visual Studio is searchResults. js , as shown in the example.

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.

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 shows your app's search results page for the user's query. This code can be found in the JavaScript file added by Visual Studio, which is called searchResults.js.
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 onactivated event that indicates the search activationKind. The Visual Studio tools register a handler that responds to this kind of activated event by showing your app's search results page for the user's query. You can find this code in the JavaScript file that Visual Studio creates, which is called searchResults.js by default.

You can learn more about activating your app in How to activate an app.

2. Complete Search contract integration

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 generateFilters function in the JavaScript file, searchResults.js.
Populate your page with results from your app's data

The app uses the searchData function 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 searchData function is defined in the JavaScript file, searchResults.js.

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 the default item template doesn't suit your search results, you should update the template. For JavaScript, you can learn more about how to create listView item templates in Styling the ListView and its items and you can find some example 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 add code to the itemInvoked function in the JavaScript file to take the user to your result details page. This file is called searchResults.js. Your navigation code should appear after the "TODO:" comment in the function.

You can learn more about basic navigation in Quickstart: Using single-page navigation.

3. Test your Search contract integration

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.

Summary and next steps

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.

If you’d like to try working with the Search charm and other key Windows 8 features, you can also download the hands-on labs for Windows 8. These labs provide a modular, step-by-step introduction to creating a sample Windows Store app in the programming language of your choice (JavaScript and HTML or C# and XAML).

For guidelines to help you design and create a good search experience for your users, see Guidelines and checklist for search.

Quickstart: Adding search to an app (Windows Store apps using JavaScript and HTML)

Prerequisites

1. Use Microsoft Visual Studio tools to add search

2. Complete Search contract integration

3. Test your Search contract integration

Summary and next steps

Related topics