Android Tutorial: Adding Search to Your Apps

Search on Android is a big topic. On every device’s homescreen is the Quick Search Box by default, older devices even had a dedicated search button. With the Quick Search Box you can quickly search the web, search for apps or contacts and search within all apps that are configured for global search. Many apps also provide local search capabilities to help you find necessary information as quickly as possible.

In this two-part tutorial series I will show you how to leverage Android’s search framework. This first part shows you the basics of Android’s search framework. In the second part I am going to cover search suggestions and global search.

Local vs. global search

There are essentially two kinds of search in Android:

  • local search and
  • global search

Local search enables users to search content of the currently visible app. Local search is appropriate for nearly every type of app. A recipe app could offer users to search for words in the title of the recipes or within the list of ingredients. Local search is strictly limited to the app offering it and it’s results are not visible outside of the app.

Global search on the other hand makes the content also accessible from within the Quick Search Box on the home screen. Android uses multiple data source for global search and your app can be one of it. In the next screen taken on a tablet you can see the results of a Google search on the left and some results from apps or for app titles on the right.

Quick Search box search results on a tablet

Quick Search box search results on a tablet

The user experience for local and global search is a bit different since global search uses multiple data sources. By default it provides search results from Google, searches for installed apps or contacts on the device and it also might include results from apps that enable global search. The following screenshot of a phone shows all content that is included in the list of search results.

Sources for Android's Quick Search Bar

Sources for Android’s Quick Search Bar

For an app to be included in this list, the user must explicitly enable it. From the perspective of the user doing the search this is a very useful restriction. That way users can limit global search to include only what they really are interested in. For app developers that tend to think that their content is the stuff any user is most likely searching for, this of course is a big letdown :-)

You should use global search only when your content is likely to be searched for from the Quick Search Box. That might be true for a friend in facebook but not necessarily for a recipe of a cooking app. I will cover configuring global search in more detail in the second part of this tutorial series.

Enabling search for your app

You always need to execute at least three steps to make your app searchable. If you want to provide search suggestions you have to add a fourth step:

  1. You have to write an xml file with the search configuration
  2. You have to write a search activity
  3. You have to tie the former two together using the AndroidManifest.xml
  4. You have to add a content provider for search suggestions – if needed

I am going to cover the first three steps in the following sections. And I am going to write about the content provider for search suggestions in the next part of this tutorial.

Configuring your search

You have to tell Android how you want your app to interact with Android’s search capabilities. This is done in an xml file. Following established practices you should name the file searchable.xml and store it in the res/xml folder of your app.

The least you have to configure is the label for the search box – even though the label is only relevant for global search. You also should always add a hint as Android displays this text within the form field. You can use this to guide the user.

<searchable 
      xmlns:android="http://schemas.android.com/apk/res/android" 
   android:label="@string/search_label"
   android:hint="@string/search_hint">
</searchable> 

There are many more attributes. I will cover those for global search in the next part of this tutorial and for voice search later on. You can find a list of all attributes on Android’s reference page.

Adding a SearchActivity

Whenever a users performs a search, Android calls an activity to process the search query. The intent used to call the activity contains the query string as an intent extra and uses the value of the static field Intent.ANDROID_SEARCH. Since you configure which activity to use for search (see next section), Android calls your activity with an explicit intent.

Most often your search activity will extend ListActivity to present a list of results to the user:

public class SampleSearchActivity extends ListActivity { 
   public void onCreate(Bundle savedInstanceState) { 
      super.onCreate(savedInstanceState); 
      handleIntent(getIntent()); 
   } 

   public void onNewIntent(Intent intent) { 
      setIntent(intent); 
      handleIntent(intent); 
   } 

   public void onListItemClick(ListView l, 
      View v, int position, long id) { 
      // call detail activity for clicked entry 
   } 

   private void handleIntent(Intent intent) { 
      if (Intent.ACTION_SEARCH.equals(intent.getAction())) { 
         String query = 
               intent.getStringExtra(SearchManager.QUERY); 
         doSearch(query); 
      } 
   }    

   private void doSearch(String queryStr) { 
   // get a Cursor, prepare the ListAdapter
   // and set it
   } 
}

So why did I include the onNewIntent() method? I did this because of Android back stack. By default Android adds every new activity on top of the activity stack. That way the functionality of the back key is supported. If a user presses the back button, Android closes the top-most activity and resumes the next activity on the stack.

Now consider a typical search behavior. The user searches for a word and has a look at the results. Oftentimes she either did not find what she were looking for or she wants to search additional information. So she clicks the search key again, enters the new search phrase and selects a suggestion. Thus a new instance of your search activity would end up on top of your previous one. The activity stack would contain the search activity twice and users would have to hit the back key twice to get back to where they were before starting the search. Which probably is not what you want. Normally you want your search activity to be on the top of the stack only once.

That’s why you should declare the activity as singleTop. That way it is only once on your stack. Should a user start a new search from within your search activity, Android would recycle the instance and call the method onNewIntent() with the new search intent as its parameter. Since the old intent is still stored within your activity, you should always call setIntent(newIntent) within your onNewIntent() method to replace the original intent with the new one.

Tying everything together in your manifest file

To make search work you have to configure it within your project’s AndroidManifest.xml file. These are the things you have to put in there:

  • Your search activity
  • The intent used for search
  • The launch mode for your activity
  • The meta-data pointing to your searchable.xml
  • Further meta-data to define which activity to use for search.

The following code shows a snippet of a typical configuration.

<application 
   android:icon="@drawable/icon" 
   android:label="@string/app_name" 
   android:name=".YourApp" > 
   <meta-data 
      android:name="android.app.default_searchable" 
      android:value=".SampleSearchActivity" /> 
   <activity 
      android:label="@string/app_name" 
      android:launchMode="singleTop" 
      android:name=".SampleSearchActivity" > 
      <intent-filter > 
         <action android:name="android.intent.action.SEARCH" /> 
      </intent-filter> 
      <intent-filter > 
         <action android:name="android.intent.action.VIEW" /> 
      </intent-filter> 
      <meta-data 
         android:name="android.app.searchable" 
         android:resource="@xml/searchable" /> 
   </activity> 
</application>

Your search activity must include the intent used for search

Android uses the value android.intent.action.SEARCH for the action within the intent when calling your search activity. So you must include this string within your activity’s intent filters. Otherwise your activity would be ignored.

The meta-data pointing to your searchable.xml

As described above you have to have an xml file to configure your search. But Android neither knows the name of this file nor its location. So Google came up with a meta-data element to point to this file.

Additional meta-data to define which activity to use for search.

Finally Android needs to know which activity to call when a search query is submitted. Again you have to use a meta-data element.

I have written a blog post about why I would prefer convention by default for these elements.

Handling search yourself

It’s important to present your user an obvious way to start search. Even when most devices had a dedicated search button you still were better of, when you added a way to manually start a search. For one users might not be familiar with the search button. But even if they know of the button they simply might not know that your app is capable of search. Thus you have to make it obvious that your app is searchable.

With the introduction of Honeycomb and Ice Cream Sandwich Android devices no longer have a search button. Instead the preferred way to present a search option is to show a search button or the search widget in the action bar.

This pattern has become common quickly and you should use an action bar with a search button even on older devices. See for example the following screenshot. It shows Gigbeat – one of my favorite apps – on an Android 2.2 device.

Action Bar with search on an Android 2.2 device

Action Bar with search on an Android 2.2 device

When the user wants to search, you have to call the search dialog from within your activity. This is done by calling onSearchRequested(). This method is part of Android’s Activity class and calls startSearch() which I will cover in a few moments.

Android’s search framework uses onSearchRequested() when the dialog should be started. Thus you should use it as well, even though it might appear odd to call a callback method directly.

Adding specific data to the search

The default search behavior is not always sufficient. First of all it only starts a local search. Most often that’s appropriate for your app, but sometimes a global search is what you need. And secondly you might want to add some specific data to the search that might depend on the state your app is in or that is specific for starting the search from this Activity only.

In these cases you have to override onSearchRequested() and call startSearch() yourself.

The method startSearch() takes four parameters which I explain in the table below.

The parameters for the startSearch() method
Parameter Type Meaning
initialQuery String A string with which to preload the search box.
selectInitialQuery boolean The flag that decides whether the content of the search box (that is the initialQuery) should be selected. If set to true any text entered overrides the initialQuery.
appSearchData Bundle Additional data to pass to the search activity.
globalSearch boolean The flag that decides whether global search should be used.

The call to startSearch() of the base class Activity uses the values null, false, null, false – which means it is a local search without any further data.

Enabling your app for voice search

To enable voice search you only have to add a few lines to your search configuration.

As you can see in the following screenshot, enabling voice search causes Android to display a microphone next to the search dialog.

Enabled voice search with microphone symbol

Enabled voice search with microphone symbol

As soon as you click the microphone the well-known voice input dialog pops up.

Voice search dialog

Voice search dialog

But not all Android devices might support voice search. If the device of a user has no voice search capabilities your voice search configuration will be ignored and the microphone symbol will not be displayed.

There are four attributes to the searchable element that deal with voice search but two should suffice in most cases.

The only obligatory attribute for voice search is android:voiceSearchMode. This attribute must contain showVoiceSearchButton, if you want to use voice search. Separated by a pipe (“|”) it needs a second value which determines the type of search: launchWebSearch or launchRecognizer.

It’s best to use launchRecognizer here, because the other value would use a web search – which normally wouldn’t yield the results appropriate for your app.

So the configuration should look like this:

android:voiceSearchMode=
      "showVoiceSearchButton|launchRecognizer"

The second important attribute is android:voiceLanguageModel. For this attribute also two types are possible: web_search and free_form.

Normally web_search should work best here – it is ideal for search like phrases where a user often won’t use correct sentences. The value free_form is more appropriate for voice input in other apps like mail or SMS that take larger chunks of well-formed text. See the developers blog post about Google’s speech input API.

One word of advice concerning voice search though: Voice search only works if the user of the app has access to the internet. If the user has no connection to the internet, Android will display an error dialog:

Voice search with connection problem

Voice search with connection problem

Wrapping up

In this part of the tutorial I have shown you how to use Android’s search framework. You have to add some configuration and add a search activity. But all in all, it’s not too difficult to add decent search capabilities to your app.

Even adding voice search requires just two lines of configuration – though you should know its limitations.

In the next part of this tutorial I will cover how to add search suggestions to your app and to the Quick Search Box on Android’s homescreen. Stay tuned!

Share this article:

You can leave a response, or trackback from your own site.

21 Responses to “Android Tutorial: Adding Search to Your Apps”

  1. […] Le saviez vous : il vous est possible d’intégrer le fonctionnement de la recherche Android dans vos applications ou bien encore de rendre les données de votre application lorsque l’utilisateur fait une recherche en dehors de votre application ? Si vous ne le saviez pas, voici un tutorial des plus complets http://www.grokkingandroid.com/android-tutorial-adding-search-to-your-apps/ […]

  2. Akhil says:

    there is a slight syntax error,

    android:hint=”@string/search_hint”

    it should be

  3. christo says:

    In this example, your manifest.xml declares the search activity as such:

    </activity

    However, the searchable activity is declared as:

    public class SampleSearchActivity extends ListActivity {
    // etc
    }

    Wouldn't it be less confusing if the class name was the same as that declared in your manifest? I know cut-and-paste coding is a bad idea anyway, but it would help to emphasize the way one connects to the other and possibly avoid confusion.

    Christo

  4. christo says:

    … it looks like my XML was stripped from the post. Not sure how to get around that, but the first quote should include the manifest.xml declaration of the activity ‘android:name=”.YourSearchActivity”‘

    thanks
    christo

  5. sohel says:

    what can i do in doSearch() method for implement search functionality.

  6. Gino says:

    great tutorial! I am wondering how the main activity calls the search activity.

    do you have the source code for this tutorial anywhere?

    thanks!

  7. Shajeel Afzal says:

    I have followed your tutorial but my SearchActivity is not starting. :(

    • So what’s the problem? “not starting” can be caused by many problems.

      BTW: It’s better to move such questions to SO. Of course you can always ping me with a link to the SO-question, if you think I can help. On SO there are thousands of helpful people. Here it’s only me – and I also need to actually have time.

      If you post this question on SO, please explain what steps you have done, add a full logcat log and add as much code as possible. In this case code of the SearchActivity, the AndroidManifest.xml and the searchable.xml are needed.

  8. Rahul says:

    Awesome Post! Thanks a lot!

    However, I have one query. Does the voice search has a callback which I can modify as per my need? I just want the search view to be filled with text when voice search is used. Currently, the search intent is called and the search view does not get filled with the search query.

    Any suggestions here?

    Thanks again for the post! Thumbs up!

  9. Rahul says:

    Awesome Blog! Thanks a lot!

  10. Tron says:

    How can i prepare my listAdapter?, i already have my cursor, but i don’t know how to prepare the listAdapter

  11. clerk says:

    Thanks for awesome post.
    i have read your hole post and followed it but i want to know how action bar hide edit text and opens when user click on search icon and then it appears. b’z i want to do that.

    • It’s the standard SearchView. You can add it to your menu.xml – all you have to do is to add those two attributes: app:actionViewClass="android.support.v7.widget.SearchView" and app:showAsAction="ifRoom|collapseActionView"/>.

      Now in your Activity/Fragment do something like this:

      SearchView searchView = 
            (SearchView) MenuItemCompat.getActionView(item);
      SearchManager searchManager = 
            (SearchManager) getSystemService(Context.SEARCH_SERVICE);
      SearchableInfo info = 
            searchManager.getSearchableInfo(getComponentName());
      searchView.setSearchableInfo(info);
      

      This will tie the SearchView to your searchable.xml – thus your SearchActivity will be called with he correct values.

      This snippet assumes you are using AppCompat.

      BTW: I think I should add this directly to the tutorial. Thanks for pointing this out. After all that’s the most common way to use search.

  12. Matthew says:

    Hi, I can see you’ve put a lot off effort into this blog.
    However, it is not useful to me, a beginner, at all.

    If you had added detailed information, showing exactly how to put things together, this would have been an excellent blog.

    But as it stands, you assume the reader knows too much, and can understand your generalisations.
    A working example project would have been great.

  13. Scott Smith says:

    Thanks for excellent post.
    I must be mixing too many things together since I can’t make it work.
    I was hoping to put a searchview (widget) in the main layout (not in the menu).
    Do you have a complete working example?
    Thanks

    • My ActionBar sample project on bitbucket contains also a simple SearchView implementation.

      I haven’t used it outside of the ActionBar yet.

      • Scott Smith says:

        I really appreciate the response and I took some time looking (and trying to install) at your example, I’m afraid it’s a little above my pay grade. I know it’s a lot to ask but if you had an extremely simple example, similar to Android Dev. guide (but they don’t explain anything well) of the search widget and processing the results of the search, I would really appreciate it or buy you a beer!
        Thanks

Leave a Reply

You can also subscribe without commenting.

Subscribe to RSS Feed My G+-Profile Follow me on Twitter!