Search

Best practice: Implementing search

• Use the net.rim.device.api.unifiedsearch package to implement search capabilities.
• Be selective with the content that you register to be included in search results. Only register content that provides meaningful search results for users.
• Try to present the most relevant items at the beginning of the list of search results. For example, if users are looking for a restaurant that has several different locations, display the restaurant that is closest to the user's location at the beginning of the list of search results.
• In the search results, bold the text that matches the text that users type. This approach helps users see why each item appears in the list of search results.
• If users need to search for a word on a screen (for example, in a message or on a web page), use the term "Find" in the Menu.

Implementing search fields

• Set the default focus to the search field. When the search results appear, set the default focus to the first item in the list of search results.
• Use the term "Search" as hint text in the search field.
• Do not make search fields case sensitive.
• Place the search field below the title bar on an application screen.
• Do not assign shortcut keys for a screen that includes a search field. If you want to use shortcut keys, provide alternative search functionality. For example, allow users to search for messages in a message list using the menu.

Create a search field

You can create an application that uses the KeywordFilterField class, included in the net.rim.device.api.ui.component package, to provide a UI field that consists of a single text input field and a list of selectable elements. As users type text in a search field, the application filters the elements in the list that begin with the search text. For more information about using the KeywordFilterField class, see the Keyword Filter Field sample application, included with the BlackBerry Java Development Environment version 4.3.1 or later.

1. Import the required classes and interfaces.

   import net.rim.device.api.collection.util.SortedReadableList;
   import net.rim.device.api.io.LineReader;
   import net.rim.device.api.ui.component.KeywordFilterField;
   import net.rim.device.api.ui.component.KeywordProvider;
   import java.io.InputStream;
   import java.lang.String;
   import java.util.Vector;

2. Create variables. In the following code sample, CountryList extends the SortedReadableList class and implements the KeywordProvider interface.

   private KeywordFilterField _keywordField;    
   private CountryList _CountryList;  
   private Vector _countries;

3. To create a list of selectable text items, populate a vector with data from a text file.

   _countries = getDataFromFile();

4. Create an instance of a class that extends the SortedReadableList class.

   _CountryList = new CountryList(StringComparator.getInstance(true),_countries);

5. To specify the elements of the list, create a new instance of a KeywordFilterField object.

   _keywordField = new KeywordFilterField();

6. Invoke KeywordFilterField.setList().

   _keywordField.setList(_CountryList, _CountryList);

7. Set a label for the input field of the KeywordFilterFIeld.

   _keywordField.setLabel("Search: ");

8. Create the main screen of the application and add a KeywordFilterField to the main screen.

   KeywordFilterDemoScreen screen = new KeywordFilterDemoScreen(this,_keywordField);
   screen.add(_keywordField.getKeywordField());
   screen.add(_keywordField);
   pushScreen(screen);

9. To create a method that populates and returns a vector of Country objects containing data from text file, in the method signature, specify Vector as the return type.

   public Vector getDataFromFile()

10. Create and store a reference to a new Vector object.

    Vector countries = new Vector();

11. Create an input stream to the text file.

    InputStream stream = getClass().getResourceAsStream("/Data/CountryData.txt");

12. Read CRLF delimited lines from the input stream.

    LineReader lineReader = new LineReader(stream);             

13. Read data from the input stream one line at a time until you reach the end of file flag. Each line is parsed to extract data that is used to construct Country objects.

    for(;;){
        //Obtain a line of text from the text file.
        String line = new String(lineReader.readLine());
    
        //If we are not at the end of the file, parse the line of text.
        if(!line.equals("EOF")) {
            int space1 = line.indexOf(" ");
            String country = line.substring(0,space1);                        
            int space2 = line.indexOf(" ",space1+1);
            String population = line.substring(space1+1,space2);                       
            String capital = line.substring(space2+1,line.length());
    
            // Create a new Country object.
            countries.addElement(new Country(country,population,capital));                                        
        }
        else {
            break;
        }
    } // End the "for" loop.
    return countries;

14. To add a keyword to the list of selectable text items, invoke SortedReadableList.doAdd(element).

    SortedReadableList.doAdd(((Country)countries.elementAt(i)).getCountryName()) ;

15. To update the list of selectable text items, invoke KeywordFilterField.updateList().

    _keywordField.updateList();

16. To obtain the keyword that a BlackBerry device user typed into the KeywordFilterField, invoke KeywordFilterField.getKeyword().

    String userTypedWord = _keywordField.getKeyword();

Autocomplete text field

You can use an autocomplete text field to predict what a BlackBerry device user wants to type, and display a word or phrase before the user types it completely.

When you create an AutoCompleteField object, you must associate a BasicFilteredList object with it. The BasicFilteredList maintains references to data objects that are compared with to produce the list of words and phrases. You can configure which fields in the data objects are compared with and which fields are displayed when a match is found. For example, you can compare the text that the user types with the value of the DATA_FIELD_CONTACTS_BIRTHDAY field in the DATA_SOURCE_CONTACTS data source, and return the value of the corresponding DATA_FIELD_CONTACTS_NAME_FULL field.

There are four types of data that you can bind to a BasicFilteredList to use with an AutoCompleteField.

You can specify the set of strings to compare with in one of the following ways:

• an array of literal strings
• an array of objects that support toString()
• data sources on a BlackBerry device, such as contacts, memos, tasks, and various types of media files
• an array of objects and an array of strings with corresponding indexes

By default, the autocomplete text field displays the set of strings that is returned by the comparison process in a drop-down list. You can configure the appearance of this list by specifying style flags when you create the autocomplete text field. You can change how the list appears and how users can interact with the list.

Create an autocomplete text field from a data set

1. Import the required classes and interfaces.

   import net.rim.device.api.ui.UiApplication;
   import net.rim.device.api.ui.container.MainScreen;
   import net.rim.device.api.ui.component.AutoCompleteField;
   import net.rim.device.api.collection.util.*;

2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the constructor, invoke pushScreen() to display the custom screen for the application. The HomeScreen class, described in step 3, represents the custom screen.

   public class AutoCompleteFieldApp extends UiApplication 
   {
       public static void main(String[] args) 
       {
           AutoCompleteFieldApp app = new AutoCompleteFieldApp();
           app.enterEventDispatcher();
       }
         
       AutoCompleteFieldApp()
       {
       	   pushScreen(new HomeScreen());
       }
   }

3. Create the custom screen by extending the MainScreen class.

   class HomeScreen extends MainScreen
   {
       public HomeScreen()
       {
       }
   }

4. In the constructor, create a BasicFilteredList object. Create a String array and store the strings that you want to match against in the array. In this example, the strings are days of the week. Invoke addDataSet() to bind the data in the array to the BasicFilteredList.

   BasicFilteredList filterList = new BasicFilteredList();
   String[] days = {"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"};
   filterList.addDataSet(1,days,"days",BasicFilteredList.COMPARISON_IGNORE_CASE);

5. In the constructor, create an AutoCompleteField object. Pass an instance of the BasicFilteredList to the AutoCompleteField constructor to bind the BasicFilteredList to the autocomplete text field. Invoke add() to add the field to the screen.

   AutoCompleteField autoCompleteField = new AutoCompleteField(filterList);
   add(autoCompleteField);

Create an autocomplete text field from a data source

1. Import the required classes and interfaces.

   import net.rim.device.api.ui.UiApplication;
   import net.rim.device.api.ui.container.MainScreen;
   import net.rim.device.api.ui.component.AutoCompleteField;
   import net.rim.device.api.collection.util.*;

2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The HomeScreen class represents the custom screen that is described in step 3.

   public class AutoCompleteFieldApp extends UiApplication 
   {
       public static void main(String[] args) 
       {
           AutoCompleteFieldApp app = new AutoCompleteFieldApp();
           app.enterEventDispatcher();
       }
       public AutoCompleteFieldApp()
       {
       	   pushScreen(new HomeScreen());
       }
   }

3. Create the custom screen for the application by extending the MainScreen class.

   class HomeScreen extends MainScreen
   {
       public HomeScreen()
       {
       }
   }

4. In the screen constructor, create a BasicFilteredList object. Invoke addDataSource() to bind a data source to the BasicFilteredList. In this example, the data is contact information and the data source is the contact list. The first argument that you pass to addDataSource() is a unique ID. The second argument binds the BasicFilteredList object to a data source. The third argument specifies the set of data source fields to compare with. The fourth argument specifies the set of data source fields to make available when a match is found. In this example, the fields to compare with are the same as the fields to make available when a match is found. The fifth argument specifies the primary display field. The sixth argument specifies the secondary display field and is set to -1 if you do not want to use it. The final argument specifies a name for the BasicFilteredList; its value is generated automatically if you specify null.

   BasicFilteredList filterList = new BasicFilteredList();
           filterList.addDataSource(
           	1,
           	BasicFilteredList.DATA_SOURCE_CONTACTS,
   
               BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL | 
               BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY | 
               BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
   
               BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL | 
               BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY | 
               BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
   
               BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL,
               -1,
               null);

5. In the screen constructor, create an AutoCompleteField object. Pass the BasicFilteredList object that you created in step 4 to the AutoCompleteField constructor to bind the BasicFilteredList to the autocomplete text field. Invoke add() to add the field to the screen.

   AutoCompleteField autoCompleteField = new AutoCompleteField(filterList);
   add(autoCompleteField);

Using data sources and fields with an autocomplete text field

You can use the AutoCompleteField class and the BasicFilteredList class to compare the text that a user types in an autocomplete text field with the values of fields in a specified data source. You specify the fields to use and their data sources by using a BasicFilteredList object that you pass as an argument to the constructor of the AutoCompleteField class.