Use the search charm to seach in the currently displayed document

Question

My app can display documents and I would like to add search functionality. I know that we should not add our own search facility to our apps but rather use the search charm. However it seems the search charms does not know the context in which to search, does it?

When the user activates it, do I get a notification in my app and can check if I am currently displaying a document. And then search only in that document rather in the whole app?

Answer 1

The short answer is yes, you get an event and your app decides what to do with it. For the long answer, there are a few subtleties:

• You can also be activated with a particular search term (it shows up as part of the activation contract) so you should handle that in case your app isn't running when the user enters a term into the search charm and then clicks on your app.
• One event you get from the search charm is after they submit the query. This is where you'd want to have your app perform the document search.
• There are other events for when the user has entered a partial query so you can suggest results to them before they submit the query.

A good starting point is here: http://msdn.microsoft.com/en-us/library/windows/apps/hh465238.aspx

Let me know if you get hung up implementing the contract, but it's pretty straightforward once you hook into the right events!

 

Cheers,

-Jeff

Answer 2

Thank you Jeff for your quick response!

I'll read through the API docs you mentioned and come back if I have more questions.

Answer 3

Hi Phil,

It sounds like you are talking about "Find on Page" functionality, the sort of functionality you would find in a PDF viewer, MS Word, or a browser via Win+F. We strongly recommend that apps offer "Find on Page" functionality in an app bar and NOT the Search Charm. The Search Charm should be used for searching over the entire scope of your app. In your case, using the search charm should leave the displayed document and return the set of items that match the search query. You may want to provide a back button to go back to the document.

Here is some more useful information how the Search Charm team differentiates Search from Find on Page:

Search operates over a set of items and returns a set of results related to the query. Search results are commonly sorted using a relevance algorithm. Search experiences enable users to operate on a single result or set of results. For example, File Search returns results from the set of files on a user’s computer, sorted based on where the file was hit (filename, property, content), and users can perform the operation of launching a single file.

Find can be thought of as “Find on Page” and operates over a continuous body of text. Only exact matches on the input string are presented to the user. These matches are commonly highlighted within the text, preserving the context around the match. Matches are returned in reading order. Find experiences enable users to move within the continuous text using direct manipulation or by jumping directly to the previous or next match.  Web browsers commonly offer find in addition to search. The find experience offered by Internet Explorer enables users to find matches for a given term in the current web page.

Apps only offering “Find on Page” functionality (e.g. document readers, text editors) should NOT use the Search charm. They should build this experience into their own app UI, potentially by using the app bar.

Thanks,
Brian

Answer 4

Thank Brian for your answer!

I will forward it to our UX team. Recent changes suggest though, that we will not even need "in document" search anymore. We will just let the user launch her prefered document viewing app associated with the currently selected document and she can use the "find" functions offered by this app. I think thats also aligning better with the Metro guidelines of creating "focused" apps. And ours is not a document viewer.

Phil