How to add SearchManager Quick Search to your Android application

Quick Search is a great thing on the Android platform. Especially since Android 1.6 will have a global suggestions list for you to add in. This means all apps that have global search enabled will show the search suggestions your app is providing. Quick Search is the little search UI that pops over your Activity when you press the looking glass search-key on your Android device. However, tapping into it with your application for the first time just sucks hard. Follow this blogpost and you’ll have search in your app in no time.

Implementing basic Android search with SearchManager in your app involves these steps:

1. Creating a search activity. This activity will display all the results for the keyword provided by the user via de Quick Search bar.
2. Adding the required elements to your AndroidManifest.xml as well as configuring a searchable.xml meta-data file.
3. Displaying results in your search activity.

Creating the search activity

I use Eclipse to develop my apps, so if you are too, create a ListActivity by creating a new Java Class in your application package. Called it something like MySearchActivity and make sure the Superclass is ListActivity.

Press Command – Shift – O to load in the required imports and add the following onCreate function:

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		final Intent queryIntent = getIntent();
		final String queryAction = queryIntent.getAction();
		if (Intent.ACTION_SEARCH.equals(queryAction)) {
			String searchKeywords = queryIntent.getStringExtra(SearchManager.QUERY);
		}
	}

You’re basically all done here. This onCreate function gets the Intent which your Activity has been called with. It contains the name of the action (ACTION_SEARCH) and the actual search keywords. You can now use the searchKeywords string to actually search your application. For example, get a web search out using a GET request or search your application’s internal sqlite database.

Adding the required elements to your AndroidManifest.xml

This part was the most tricky for me. The Android SearchManager documentation just had a jungle of information on it but it’s just too much to handle and hard to distill the actual information from. So save yourself some time and let me tell you what you need to add.

For the activity that actually displays the search results – the activity we created in the previous step – add the following:

<activity android:name="MySearchActivity"
                  android:label="Search">
            <intent-filter>
                <action android:name="android.intent.action.SEARCH" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
            <meta-data android:name="android.app.searchable"
                       android:resource="@xml/searchable" />
        </activity>

This activity element tells your application that the MySearchActivity is an Activity that can be used to invoke the search. It contains a meta-data element which is a pointer to an xml file that contains meta information for the search UI and behavior, such as labels and wether to include global search suggestions. This is the bit where I went wrong so pay close attention.

Now, right-click your res/ folder and create a new Android XML file called searchable.xml. Select Searchable from the options of file types. Eclipse should now create the res/xml/searchable.xml file. It will create the xml/ directory if it didn’t exist yet. In this file, add the following:

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

The contents of this file configures how the search field is displayed and you can set a lot of options for the behavior. Read about all the options in the SearchManager#SearchabilityMetadata section of the Android Developer documentation. Your own search bar won’t work if you don’t use @string resources for the configuration keys in this file. So don’t use static strings because they won’t work and you’ll loose precious hours of development time to debugging, like I did.

So, add the search_label and search_hint strings to res/values/strings.xml and put in something nice.

Displaying results in your search activity

So we have the initial onCreate function with the search keyword, and we’ve configured the search UI to pop up when the user presses the search key. Now it’s time for displaying the actual results. I will not get into technical details here because you can implement this in a lot of ways. Maybe I’ll dedicate the next blog post to this part. For now, do the the following:

• Based on the searchKeywords string you have, fire up your search in your local sqlite database or do some HTTP requests to fetch a list of search results from.
• Add them into an ArrayAdapter<MyClass> with nice formatting.
• Bind the ArrayAdapter<MyClass> with the SearchActivity by calling setListAdapter(myListAdapter) in the onCreate function.
• You’re ready to go!

Take a look at ListActivity on the Android Developer site.

Conclusion

If you know the right – and actually simple – steps, implementing search in your application is easy. It’s the actual researching of the docs that suck. Please feel free to leave a comment or reply me on Twitter at @michiels.

More of my posts on this topic:

1. Android 1.6 Donut released

Tagged as: Android, code, quick, search example