Merge "docs: editorial revisions to Search guide" into froyo

<div id="qv-wrapper">

<div id="qv">

<h2>Key classes</h2>

<ol>

<li>{@link android.provider.SearchRecentSuggestions}</li>

<li>{@link android.content.SearchRecentSuggestionsProvider}</li>

</ol>

<h2>In this document</h2>

<ol>

<li><a href="#TheBasics">The Basics</a></li>

<li><a href="#RecentQuerySearchableConfiguration">Modifying the searchable

configuration</a></li>

<li><a href="#RecentQueryContentProvider">Creating a Content Provider</a></li>

<li><a href="#SavingQueries">Saving queries</a></li>

<li><a href="#ClearingSuggestionData">Clearing the suggestion data</a></li>

<li><a href="#RecentQuerySearchableConfiguration">Modifying the Searchable

Configuration</a></li>

<li><a href="#SavingQueries">Saving Queries</a></li>

<li><a href="#ClearingSuggestionData">Clearing the Suggestion Data</a></li>

</ol>

<h2>Key classes</h2>

<ol>

<li>{@link android.provider.SearchRecentSuggestions}</li>

<li>{@link android.content.SearchRecentSuggestionsProvider}</li>

</ol>

<h2>See also</h2>

<ol>

<li><a href="searchable-config.html">Searchable Configuration</a></li>

</div>

</div>

<p>The Android search framework provides the ability for your application to

provide suggestions while the user types into the Android search dialog. In this guide, you'll learn

how to create recent query suggestions. These are suggestions based

on queries previously entered by the user. So, if the user previously searched for "puppies" then it

will appear as a suggestion as they begin typing the same string of text. The screenshot below

shows an example of recent query suggestions.</p>

<p>When using the Android search dialog, you can provide search suggestions based on recent search

queries. For example, if a user previously searched for "puppies," then that query appears as a

suggestion once he or she begins typing the same query. Figure 1 shows an example of a search dialog

with recent query suggestions.</p>

<p>Before you begin, you need to implement the search dialog for basic searches in your application.

If you haven't, see <a href="search-dialog.html">Using the Android Search Dialog</a>.</p>

<p>Before you begin, you need to have implemented the Android search dialog for searches in your

application. If you haven't done this, see <a href="search-dialog.html">Using the Android Search

Dialog</a>.</p>

<h2 id="TheBasics">The Basics</h2>

<img src="{@docRoot}images/search/search-suggest-recent-queries.png" alt="" height="417"

style="float:right;clear:right;" />

<div class="figure" style="width:250px">

<img src="{@docRoot}images/search/search-suggest-recent-queries.png" alt="" height="417"  />

<p class="img-caption"><strong>Figure 1.</strong> Screenshot of a search dialog with recent query

suggestions.</p>

</div>

<p>Recent query suggestions are simply saved searches. When the user selects one of

the suggestions, your searchable Activity will receive a normal {@link

the suggestions, your searchable Activity receives a {@link

android.content.Intent#ACTION_SEARCH} Intent with the suggestion as the search query, which your

searchable Activity will already handle.</p>

searchable Activity already handles (as described in <a href="search-dialog.html">Using the Android

Search Dialog</a>).</p>

<p>To provide recent queries suggestions, you need to:</p>

<ul>

  <li>Implement a basic searchable Activity, as documented in <a

href="{@docRoot}guide/topics/search/search-dialog.html">Using the Android Search Dialog</a>.</li>

  <li>Implement a searchable Activity, <a

href="{@docRoot}guide/topics/search/search-dialog.html">using the Android Search Dialog</a>.</li>

  <li>Create a content provider that extends {@link

android.content.SearchRecentSuggestionsProvider} and declare it in your application manifest.</li>

  <li>Modify the searchable configuration with information about the content provider.</li>

  <li>Save queries to your content provider each time a search is made.</li>

  <li>Modify the searchable configuration with information about the content provider that

provides search suggestions.</li>

  <li>Save queries to your content provider each time a search is executed.</li>

</ul>

<p>Just like the Search Manager handles the rendering of the search dialog, it will also do the work

to display all search suggestions below the search dialog. All you need to do is provide a source

from which the suggestions can be retrieved.</p>

<p>Just as the Search Manager displays the search dialog, it also displays the

search suggestions. All you need to do is provide a source from which the suggestions can be

retrieved.</p>

<p>When the Search Manager identifies that your Activity is searchable and also provides search

suggestions, the following procedure will take place as soon as the user types into the Android

search box:</p>

<p>When the Search Manager identifies that your Activity is searchable and provides search

suggestions, the following procedure takes place as soon as the user types into the search

dialog:</p>

<ul>

  <li>The Search Manager takes the search query text (whatever has been typed so far) and performs a

query to the content provider that manages your suggestions.</li>

  <li>Your content provider then returns a {@link android.database.Cursor} that points to all

suggestions that are relevant to the search query text.</li>

  <li>The Search Manager then displays the list of suggestions provided by the Cursor (as

demonstrated in the screenshot to the right).</li>

</ul>

<ol>

  <li>Search Manager takes the search query text (whatever has been typed so far) and performs a

query to the content provider that contains your suggestions.</li>

  <li>Your content provider returns a {@link android.database.Cursor} that points to all

suggestions that match the search query text.</li>

  <li>Search Manager displays the list of suggestions provided by the Cursor.</li>

</ol>

<p>At this point, the following may happen:</p>

<p>Once the recent query suggestions are displayed, the following might happen:</p>

<ul>

  <li>If the user types another key, or changes the query in any way, the above steps are repeated

and the suggestion list is updated as appropriate.</li>

  <li>If the user types another key, or changes the query in any way, the aforementioned steps are

repeated and the suggestion list is updated.</li>

  <li>If the user executes the search, the suggestions are ignored and the search is delivered

to your searchable Activity using the normal {@link android.content.Intent#ACTION_SEARCH}

Intent.</li>

  <li>If the user selects a suggestion, a normal

{@link android.content.Intent#ACTION_SEARCH} Intent is triggered, using the suggested text as the

query.</li>

  <li>If the user selects a suggestion, an

{@link android.content.Intent#ACTION_SEARCH} Intent is delivered to your searchable Activity using

the suggested text as the query.</li>

</ul>

<p>As you'll soon discover, the {@link android.content.SearchRecentSuggestionsProvider} class that

you'll extend for your content provider will automatically do the work described above, so there's

<p>The {@link android.content.SearchRecentSuggestionsProvider} class that

you extend for your content provider automatically does the work described above, so there's

actually very little code to write.</p>

<h2 id="RecentQuerySearchableConfiguration">Modifying the searchable configuration</h2>

<p>First, you need to add the {@code android:searchSuggestAuthority} and

{@code android:searchSuggestSelection} attributes to the {@code <searchable>} element in your

searchable configuration file. For example:</p>

<pre>

<?xml version="1.0" encoding="utf-8"?>

<searchable xmlns:android="http://schemas.android.com/apk/res/android"

    android:label="@string/app_label"

    android:hint="@string/search_hint"

    android:searchSuggestAuthority="my.package.MySuggestionProvider"

    android:searchSuggestSelection=" ?" >

</searchable>

</pre>

<p>The value for {@code android:searchSuggestAuthority} should be a fully-qualified name for

your content provider: your application package name followed by the name of your content provider.

This string must match the authority used in the content provider (discussed in the next section).

</p>

<p>The value for {@code android:searchSuggestSelection} must be a single question-mark, preceded by

a space (" ?"), which is simply a placeholder for the SQLite selection argument (which will be

automatically replaced by the query text entered by the user).</p>

<h2 id="RecentQueryContentProvider">Creating a Content Provider</h2>

<pre>

public class MySuggestionProvider extends SearchRecentSuggestionsProvider {

    public final static String AUTHORITY = "my.package.MySuggestionProvider";

    public final static String AUTHORITY = "com.example.MySuggestionProvider";

    public final static int MODE = DATABASE_MODE_QUERIES;

    public MySuggestionProvider() {

}

</pre>

<p>The call to {@link android.content.SearchRecentSuggestionsProvider#setupSuggestions(String,int)}

passes the name of the search authority (matching the one in the searchable configuration) and a

database mode. The database mode must include {@link

<p>The call to {@link android.content.SearchRecentSuggestionsProvider#setupSuggestions(String,int)

setupSuggestions()} passes the name of the search authority and a

database mode. The search authority can be any unique string, but the best practice is to use a

fully qualified name for your content provider

(package name followed by the provider's class name; for example,

"com.example.MySuggestionProvider"). The database mode must include {@link

android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_QUERIES} and can optionally include

{@link

android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}, which will add another column

android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}, which adds another column

to the suggestions table that allows you to provide a second line of text with each suggestion. For

example:</p>

example, if you want to provide two lines in each suggestion:</p>

<pre>

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

</pre>

<p>In the following section, you'll see how to save both lines of text.</p>

<p>Now simply declare the content provider in your application manifest with the same authority

string used in the class (and in the searchable configuration). For example:</p>

<p>Now declare the content provider in your application manifest with the same authority

string used in your {@link android.content.SearchRecentSuggestionsProvider} class (and in the

searchable configuration). For example:</p>

<pre>

<application>

    <provider android:name=".MySuggestionProvider"

              android:authorities="my.package.authority" />

              android:authorities="com.example.MySuggestionProvider" />

    ...

</application>

</pre>

<h2 id="SavingQueries">Saving queries</h2>

<p>In order to populate your collection of recent queries, you need to add each query

received by your searchable Activity to the content provider you've just built. To do this, create

an instance of {@link

<h2 id="RecentQuerySearchableConfiguration">Modifying the Searchable Configuration</h2>

<p>To configure your search dialog to use your suggestions provider, you need to add

the {@code android:searchSuggestAuthority} and {@code android:searchSuggestSelection} attributes to

the {@code &lt;searchable&gt;} element in your searchable configuration file. For example:</p>

<pre>

<?xml version="1.0" encoding="utf-8"?>

<searchable xmlns:android="http://schemas.android.com/apk/res/android"

    android:label="@string/app_label"

    android:hint="@string/search_hint"

    <b>android:searchSuggestAuthority="com.example.MySuggestionProvider"

    android:searchSuggestSelection=" ?"</b> >

</searchable>

</pre>

<p>The value for {@code android:searchSuggestAuthority} should be a fully qualified name for

your content provider that exactly matches the authority used in the content provider (the {@code

AUTHORITY} string in the above example).

</p>

<p>The value for {@code android:searchSuggestSelection} must be a single question mark, preceded by

a space ({@code " ?"}), which is simply a placeholder for the SQLite selection argument (which is

automatically replaced by the query text entered by the user).</p>

<h2 id="SavingQueries">Saving Queries</h2>

<p>To populate your collection of recent queries, add each query

received by your searchable Activity to your {@link

android.content.SearchRecentSuggestionsProvider}. To do this, create an instance of {@link

android.provider.SearchRecentSuggestions} and call {@link

android.provider.SearchRecentSuggestions#saveRecentQuery(String,String)} each time your searchable

Activity receives a query. For example, here's how you can save the query during your

Activity's {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</p>

android.provider.SearchRecentSuggestions#saveRecentQuery(String,String) saveRecentQuery()} each time

your searchable Activity receives a query. For example, here's how you can save the query during

your Activity's {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</p>

<pre>

@Override

}

</pre>

<p>Notice that the {@link android.content.SearchRecentSuggestionsProvider} constructor requires the

<p>The {@link android.content.SearchRecentSuggestionsProvider} constructor requires the

same authority and database mode declared by your content provider.</p>

<p>The {@link android.provider.SearchRecentSuggestions#saveRecentQuery(String,String)} method takes

<p>The {@link android.provider.SearchRecentSuggestions#saveRecentQuery(String,String)

saveRecentQuery()} method takes

the search query string as the first parameter and, optionally, a second string to include as the

second line of the suggestion. The second parameter is only used if you've enabled two-line mode

for the search suggestions with {@link

second line of the suggestion (or null). The second parameter is only used if you've enabled

two-line mode for the search suggestions with {@link

android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}. If you have enabled

two-line mode, then the query text will be matched against this second line as well.</p>

two-line mode, then the query text is also matched against this second line when the Search Manager

looks for matching suggestions.</p>

<p>That's all that's needed to build a recent queries suggestion provider. However, there's one

other important thing to do: provide the ability for the user to clear this search history.</p>

<h2 id="ClearingSuggestionData">Clearing the suggestion data</h2>

<h2 id="ClearingSuggestionData">Clearing the Suggestion Data</h2>

<p>To protect the user's privacy, you should always provide a way for the user to clear the recent

query suggestions. To clear the recent queries, simply call {@link

query suggestions. To clear the query history, call {@link

android.provider.SearchRecentSuggestions#clearHistory()}. For example:</p>

<pre>

suggestions.clearHistory();

</pre>

<p>Simply execute this from your choice of a "Clear Search History" menu item,

preference item, or button. You should also provide a confirmation dialog when this is pressed, to

<p>Execute this from your choice of a "Clear Search History" menu item,

preference item, or button. You should also provide a confirmation dialog to

verify that the user wants to delete their search history.</p>

<ol>

<li><a href="searchable-config.html">Searchable Configuration</a></li>

</ol>

<h2>See also</h2>

<h2>Related Samples</h2>

<ol>

<li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable

Dictionary sample app</a></li>

Dictionary</a></li>

</ol>

</div>

</div>

<p>The ability to search is considered to be a core user feature on Android. The user should be able

to search any data that is available to them, whether the content is located on the device or the

Internet. This experience should be seamless and consistent across the entire

system, which is why Android provides a simple search framework to help you provide users with

<p>Search is a core user feature on Android. Users should be able

to search any data that is available to them, whether the content is located on the device or

the Internet. The search experience should be seamless and consistent across the entire

system, which is why Android provides a search framework to help you provide users with

a familiar search dialog and a great search experience.</p>

<img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417"

style="float:right;clear:right;" />

<div class="figure" style="width:250px">

<img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417" />

<p class="img-caption"><strong>Figure 1.</strong> Screenshot of a search dialog with custom

search suggestions.</p>

</div>

<p>Android's search framework provides a user interface in which users can perform a search and

an interaction layer that communicates with your application, so you don't have to build

your own search Activity. Instead, a search dialog appears at the top of the screen at the user's

command without interrupting the current Activity.</p>

<p>Android's search framework provides a user interface in which the user can perform a search and

an interaction layer that communicates with your application. This way, you don't have to build

a search box that the user must find in order to begin a search. Instead,

a custom search dialog will appear at the top of the screen at the user's command.

The search framework will manage the search dialog and when the user executes their search, the

search framework will pass the query text to your application so that your application can begin a

search. The screenshot to the right shows an example of the search dialog (using

search suggestions).</p>

<p>The search framework manages the life of the search dialog. When users execute a search, the

search framework passes the query text to your application so your application can perform a

search. Figure 1 shows an example of the search dialog with optional search suggestions.</p>

<p>Once your application is set up to use the search dialog, you can:</p>

<ul>

<li>Customize some of the search dialog characteristics</li>

<li>Enable voice search</li>

<li>Provide search suggestions based on recent user queries</li>

<li>Provide search suggestions that match actual results in your application data</li>

<li>Provide custom search suggestions that match actual results in your application data</li>

<li>Offer your application's search suggestions in the system-wide Quick Search Box</li>

</ul>

<p>The following documents will teach you how to use the search dialog in

your application:</p>

<p class="note"><strong>Note</strong>: The search framework does <em>not</em> provide APIs to

search your data. To perform a search, you need to use APIs appropriate for your data. For example,

if your data is stored in an SQLite database, you should use the {@link android.database.sqlite}

APIs to perform searches.</p>

<p>The following documents show you how to use the search dialog in your application:</p>

<dl>

  <dt><strong><a href="search-dialog.html">Using the Android Search Dialog</a></strong></dt>

  <dd>How to set up your application to use the search dialog for searches. </dd>

  <dd>How to set up your application to use the search dialog. </dd>

  <dt><strong><a href="adding-recent-query-suggestions.html">Adding Recent Query

Suggestions</a></strong></dt>

  <dd>How to show suggestions based on queries previously used in the search dialog.</dd>

  <dt><strong><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></strong></dt>

  <dd>How to show suggestions based on custom data from your application and offer your suggestions

in the system-wide Quick Search Box.</dd>

  <dt><strong><a href="searchable-config.html">Searchable Configuration</a></strong></dt>

  <dd>A reference for the searchable configuration file (though the other

documents also discuss the configuration file in terms of specific behaviors).</dd>

</dl>

<p>Also, the <strong><a href="searchable-config.html">Searchable Configuration</a></strong> document

provides a reference for the searchable configuration file (though the above

documents also discuss the configuration file in terms of specific behaviors).</p>

<p class="note"><strong>Note</strong>: The search framework does <em>not</em> provide APIs to

perform searches on your data. Performing actual searches is a task that you must accomplish

using APIs appropriate for your data, such as those in {@link android.database.sqlite}

if your data is in an SQLite database.</p>

<h2>Protecting User Privacy</h2>

<p>When you implement search in your application, you should take steps to protect the user's

privacy whenever possible. Many users consider their activities on the phone, including searches, to

be private information. To protect the user's privacy, you should abide by the following

<p>When you implement search in your application, take steps to protect the user's

privacy. Many users consider their activities on the phone—including searches—to

be private information. To protect each user's privacy, you should abide by the following

principles:</p>

<ul>

<li><strong>Don't send personal information to servers, and if you do, don't log it.</strong>

<p>"Personal information" is information that can personally identify your users, such as their

name, email address, billing information, or other data which can be reasonably linked to such

information. If

your application implements search with the assistance of a server, try to avoid sending personal

information along with the search queries. For example, if you are searching for businesses near a

zip code,

you don't need to send the user ID as well — send only the zip code to the server. If you must

send the personal information, you should take steps to avoid logging it. If you must log it, you

should protect that data very carefully and erase it as soon as possible.</p>

<li><strong>Don't send personal information to servers, but if you must, do not log it.</strong>

<p>Personal information is any information that can personally identify your users, such as their

names, email addresses, billing information, or other data that can be reasonably linked to such

information. If your application implements search with the assistance of a server, avoid sending

personal information along with the search queries. For example, if you are searching for businesses

near a zip code,

you don't need to send the user ID as well; send only the zip code to the server. If you must

send the personal information, you should not log it. If you must log it, protect that data

very carefully and erase it as soon as possible.</p>

</li>

<li><strong>Provide the user with a way to clear their search history.</strong>

<p>The search framework helps your application provide context-specific suggestions while they type.

Sometimes these

suggestions are based on previous searches, or other actions taken by the user in an earlier

session. A user may not wish for previous searches to be revealed to other users, for instance if

they share their phone with a friend. If your application provides suggestions that can reveal

previous activities, you should implement a "Clear History" menu item, preference, or button. If you

are

using {@link android.provider.SearchRecentSuggestions}, you can simply call its {@link

android.provider.SearchRecentSuggestions#clearHistory()} method. If you are implementing custom

suggestions, you'll need to provide a

similar "clear history" method in your provider that can be invoked by the user.</p>

<p>The search framework helps your application provide context-specific suggestions while the user

types. Sometimes these

suggestions are based on previous searches or other actions taken by the user in an earlier

session. A user might not wish for previous searches to be revealed to other device users, for

instance, if they share their phone with a friend. If your application provides suggestions that can

reveal previous activities, you should implement the ability for the user to clear the search

history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply call the

{@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are implementing

custom suggestions, you'll need to provide a similar "clear history" method in your provider that

the user can execute.</p>

</li>

</ul>