Tutorial 8 How to create a Searchable List

What you will learn in this Tutorial

How to Create a Searchable List

Download Source Code - Tutorials - Source for this tutorial is in appemble-tutorial-list
Learn more FAQ

Must Read

Tutorial 6 How to create a list

Good Read

Tutorial - How to Navigate from LIST Control

Tutorial - How to create a section list

Reference LIST control

Introduction

Pre-requisite for this tutorial is Tutorial 6 How to create a list. A searchable list is one, where user can filter the items in the list box. The filter can be based on items that begin with the search criteria or on items that contain the search criteria. In this tutorial you are going to learn how to create a searchable list.

Android

../_images/searchable_list_blank_small1.png ../_images/searchable_list_small1.png ../_images/searchable_list1_small1.png

iOS

../_images/ios_searchlist1.png ../_images/ios_searchlist2.png ../_images/ios_searchlist3.png

Fig 1 Displays the list with all the items Fig 2 and 3 Display search result based on the words that begin with letters typed.

Note

The source code for this tutorial is in appemble-tutorial-list

Create a Searchable List

Search result can be specified to

  • Display list of all words that INCLUDE the letter / letters typed in the search criteria edit box. (default behaviour)
  • Display list of all words that BEGIN_WITH the letter / letters typed in the search criteria edit box. (has to be specified as Search criteria)

This tutorial extends the list tutorial project from Tutorial 7. Lets create another screen called searchablelist.xml. In the sample code below, look carefully at the hierarchy of controls.

<control type="SEARCHABLE_LIST".......>
    <control type="EDIT"........./>         <!--Child control of SEARCHABLE_LIST-->
    <control type="LIST"..........>         <!--Child control of SEARCHABLE_LIST-->
        <control type="TEXT"........./>     <!-- Child control of LIST-->
    </control>
</control>

Attributes specific to Searchable list

  • control type=”SEARCHABLE_LIST”
  • control type=”EDIT” hint=”search” - This is used for displaying text before the user enters any text
  • control type=”LIST” search_criteria=”BEGINS_WITH” local_data_resource=”select ........like &apos;%SEARCH%&apos;....
  • search_criteria=”BEGINS_WITH” OR search_criteria=”CONTAINS”. If no value search_criteria is not specified, default is “CONTAINS”

Note

  • search_criteria="BEGINS_WITH" specifies the search criteria. If no value is specified in search_criteria, then by default the result will be list of all words containing the search string.
  • The query provided in the local_data_source must have apostrophe before and after %SEARCH% if the search field is a string. For ex. Select .. from ... where field1 like &apos;%SEARCH%&apos;
  • There is slight difference in the implementation between Android and iOS. In iOS, the edit box for SEARCHABLE_LIST automatically appears at the top of the list while in Android it has to be user specified. By having an attribute os=”2” in a control, means that this control is to be created only for Android. If the control is to be created only for iOS, then define the attribute os=”1”. By default controls are common across all platforms with few exceptions and SEARCHABLE_LIST is one of them.
  • SEARCHABLE_LIST performs searches on one or more fields based on how you construct the query. For ex. the following query would search in both item and description field. SELECT list_item_id as _id, item, description FROM myshopping_list WHERE item like &apos;%SEARCH%&apos; or description like &apos;%SEARCH%&apos; order by item
  • The local_data_source for LIST MUST contain a query and it MUST include %SEARCH%

Create searchablelist.xml

<screens>
    <screen name="searchablelist" screen_type="SCREEN" menuOrder="2"
            menuName="Searchable" initial_layout="PORTRAIT"
            allowed_layouts="BOTH"
            width="100" height="100" tab_group_name="tabgroup1">

        <title_controls>
            <control type="TEXT" x="0" y="1" width="100" height="6"
                    default_value="Searchable list" appearance_name="white"
                    data_type="VARCHAR">
            </control>
        </title_controls>

        <controls>
            <control type="SEARCHABLE_LIST" x="0" y="0" width="100"
                    height="100" appearance_name="black" os="2"
                    search_criteria="BEGINS_WITH">
                <control name="search_box" type="EDIT" x="1" y="1"
                        width="98" height="8" appearance_name="edit_box"
                        hint="search" os="2"
                        permission="READONLY" />
                <control type="LIST" x="0" y="10" width="100" height="100"
                        permission="READONLY" appearance_name="black"
                        data_type="CURSOR"
                        local_data_source="select list_item_id as _id, item,
                    category from myshopping_list where (item like &apos;
                    %SEARCH%&apos; or category like &apos;%SEARCH%&apos;)
                    order by item"
                        os="2">
                    <control type="TEXT" x="3" y="2" width="27" height="7"
                            permission="READONLY" appearance_name="black"
                            data_type="VARCHAR"
                            field_name="item" os="2" />
                    <control type="TEXT" x="35" y="2" width="50" height="7"
                            permission="READONLY" appearance_name="black"
                            data_type="VARCHAR"
                            field_name="category" />
                </control>
            </control>
            <control type="SEARCHABLE_LIST" x="0" y="0" width="100"
                    height="100" appearance_name="black" os="1"
                    local_data_source="select list_item_id as _id, item, category
                from myshopping_list where item like &apos;%SEARCH%&apos;
                order by item">
                <control type="TEXT" x="3" y="2" width="27" height="7"
                        permission="READONLY" appearance_name="black"
                        data_type="VARCHAR"
                        field_name="item" os="1" />
                <control type="TEXT" x="35" y="2" width="50" height="7"
                        permission="READONLY" appearance_name="black"
                        data_type="VARCHAR"
                        field_name="category" />
            </control>
        </controls>
    </screen>
</screens>

The app is ready for testing

Android - Right click on the project and click on Run as Android application.

iOS - Click on Product -> Run.

Download and Run Tutorials

This chapter uses source code from appemble-tutorial-list. If you have not downloaded tutorial source code, click on Download Source Code - Tutorials

Android - Right click on appemble-tutorial-list and click on Run as Android application.

iOS - Select scheme appemble-tutorial-list and iPhone x.x simulator. Click on Product -> Run.

FAQ

Is the search case sensitive?

Yes the search is case sensitive.

Can the search be case insensitive?

Yes you can make the search case sensitive by formulating the query in the right way SELECT * FROM ... WHERE UPPER(name) = UPPER(‘someone’) or SELECT * FROM ... WHERE name = ‘someone’ COLLATE NOCASE

Can I search on database columns that are not part of the list?

Yes you can have any column in the where clause as long as it exists in your table. You can certainly perform complex joins across tables to get the data to the searchable list box. Just make sure that the columns of the SELECT statement must match the field_names of the child controls of the LIST control.