HowTo: In-app search in Smart Devices

Official Content
This documentation is valid for:

The increasing amount of data managed by an application is a reality. Nowadays, it is vital for every system to display content to the end user as quickly as possible and in a friendly way.
In order to achieve this aim, GeneXus provides two different but closely related components to enhance this essential element called Search Pattern.

SearchBox control

The SearchBox control is a facility for the developers to improve the search mechanism in their applications. Its aim is to store the last keyword that the end user wants to search and give a friendly UI for them.

Warning: When the developer uses a search-box control should not set Enter Event property because the keyboard enter action will always execute a search.

Adding the control

1) Create a string variable in a Panel (Character, VarChar or LongVarChar).
2) Drag it from the toolbox and drop it in the abstract layout.
3) Set Control Type property in SearchBox.
These steps are summarized in the following image.
SearchBox - Summarized steps

Properties

When Control Type property is set with SearchBox value, new properties are displayed.

Property Values Description
Type Dynamic (default) The search-box will be displayed on the application bar once the end user focuses on it.
Explicit The search-box is not going to be displayed on the application bar until the end user execute a search (i.e. the search button on the keyboard).
     
Result Panel (none) This property is the essential item in the Search Pattern. It must be set with a Panel (specially designed) by the developer in order to display the search result. In such panel is where the search box will be displayed on the application bar. See Tips section for a canonical example.

Methods

DoSearch

It helps the developer to call the search Result Panel programmatically in a client-side event with the value set in It.
For example, if &SearchedText  is the variable defined with SearchBox control, then the developer can write the following sentence: &SearchBox.DoSearch()

Parameters None
Return None

Usage example

Designing the Result Panel

The first decision to make is to properly design the Result Panel which shows the result of the search.
You might be interested in the rules that must be followed to design it properly.

1st - Adding a parm rule

The Result Panel is called implicitly by the main object which includes the associated SearchBox control.
Remember that this control only applies to string variables (i.e. Character, VarChar, LongVarChar domains) that contain the searched word or sequence of them.
For that reason, the Result Panel must include a parm rule that receives this string in order to show the result.

parm(&SearchedText) 

The variable received in this rule is declared without in/out directives, because it can be helpful to assign it or simply read it.

2nd - Include a grid with a condition

The Result Panel's aim is to show a set of records that match with the keyword. 
For that reason, It is necessary to include a Grid control and then set a condition over it to filter the content.
Generally, this condition takes advantage of the Like operator and the '%' wildcard character, allow the developer to write a condition like:

MyStringAttribute LIKE '%'+&SearchedText;

Where &SerchedText is the string variable received in the parm rule and MyStringAttribute some string attribute that we want to match the text.

Summarizing, the complete process to create the Result Panel is similar to that described in the image below.

Search Pattern - PanelResult

Adding features to the Result Panel

The Search external object purpose is to define events in the Result Panel in order to be triggered when the end user executes a certain condition.
For example, it can be useful to refresh the Grid in the Result Panel when the text changes. Consequently, an event like this can be written: 

Event Search.SearchTextChanged(&vText)
    &SearchedText = &vText
    refresh
EndEvent

Remember that &SerchedText is the string variable received in the parm rule. 

Download

You can download this example from here.

Notes

  • On Android devices, the SearchBox control will be shown in place of the application bar. Then, it can be customizable by its respective theme class (e.g. Forecolor of the searched text).

Scope

Objects Panel for Smart DevicesWork With for Smart Devices 
Domains Character, VarChar, LongVarChar
SD Generators iOS, Android
Languages .NET, Java

Availability

This article applies as from GeneXus 15.





Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.