How Do I Add Search And Find To My DataGrid Form?
This example will demonstrate how DGH can provide the following two tasks for data grid forms: finding values inside the data grid and altering rows displayed to only show those containing the found values.
Prepare The Required Controls In A Stack
For this example, we will require:
(1) a data grid form conveniently preloaded with some data.
(2) an editable field. This field will allow us to input a value to find inside the data grid.
(3) a label for displaying how many rows in the data grid correspond to containing the search value.
Once the controls are created, we can open DGH for the data grid and expand the Action Scripts topic (4).
Link The Search Field With The Data Grid
The first step is to associate our search field with the Search/Find action.
We will select the editable field by using the DGH's Control Picker.
Open the Control Picker for the Search/Find property by clicking on its modify ... button. Then click on the Choose button in the resulting open a window.
Move The Mouse Over The Editable Field
Place the mouse over the editable field you added earlier. DGH informs you by displaying a tooltip that the editable field is eligible for selection by. (1)
Note the Control Picker has changed and the Choose button is now a Cancel button. (2)
Select The Editable Field As The Search/Find Field
Click onto the field to select it.
The Control Picker has now changed the Cancel button to a Confirm button. (1)
Click the Confirm button to link the data grid to the search field. (2)
Basically, this simple click has installed several handlers:
- in the field itself
- in the data grid
- in the card holding the data grid
- in the data grid row behavior
The long id of the linked field is now displayed inside the property for Search/Find.
Add A “Counting The Rows Found” Feature.
The Search/Find feature installed by DGH is also capable of counting how many rows correspond to the value entered in the query field.
To do this, expand the Action Parameters section in the Table Properties view and click the modify ... button for the Found Rows Count Label line.
In exactly the same way we just associated the query field with the Search/Find action, associate the label field with the Found Count Rows Label action.
Click the Choose button in the Control Picker we just opened, move the mouse to the label field (1) and click on it, and finally, click on the Confirm button (2) that is now showing in the Control Picker.
The long id of the label field is now displayed inside the Found Count Rows Label property.
Testing The Search Field And Its Information Label
We can now test the search field by inputing a some text and see if all is working as expected.
The found values are displayed with a yellow background, and the information label shows that there are 3 rows containing the search query ("text") among the 4 rows of the data grid.
Going Further: Editing the Action Parameters
The test above displays the default options for these actions. DGH provides some parameters to modify these defaults.
With the data grid selected, expand the Action Parameters topic in the DGH's Form Properties view.
To change the highlight color of the "text found", click on the color well for the Find Color property.
To return to the default yellow, click on the eraser icon.
To see the modification take effect, change the text in the Search/Find field.
To change the Found Rows Text Pattern, double-click on the existing text in that property's value area..
Note: #FoundRows# and #RowsNumber# are two place holders which will be replaced by the DGH installed script, respectively with the rows found and the numbers of rows inside the data grid.
For example replace the existing text with: “Found lines : #FoundRows# among #RowsNumber# rows”
Here is a preview of the changes, inside our data grid example.
Searching And Filtering The Rows Inside The Data Grid To Display Only The Successful Rows
The simple find feature previously added does not require any change in the dgData of the data grid.
However there are times when it would be preferred to filter the data displayed so as to only show the rows containing the searched for text.
To filter the data displayed in the data grid as a result of our find, we will need to change the dgData being displayed. This also means we need to "save" our original dgData so that we can restore it whenever the search text is changed or deleted.
As a result, this feature is not active by default.
To activate the filter feature you will need to uncomment the relevant handler call in the card script created by DGH when the find field was enabled.
Open the card script, then the DGH_Search_Launch handler.
As you can see the script gives the details of what needs to be done:
Uncomment the line: --DGH_Search_FilterDGByIndexes pTheDGName, tTheIndexFound
## Search Field Script command DGH_Search_Launch pTheDgName, pTheString, pTheKeysList, pTheFilterOperator local tTheIndexFound if (pTheString is empty) then DGH_Search_Clear pTheDgName put empty into tTheIndexFound else set the dghProp["dg is in search mode"] of grp pTheDGName to true DGH_Search_RowsByValue pTheDGName, pTheKeysList, pTheFilterOperator, pTheString put the result into tTheIndexFound /* Filtering found rows Rather than simply hiliting the found text, the following command enables you to filter the data displayed by the data grid to only those rows containing the searched for text. Note: This function requires the original data displayed in the data grid to be saved so that it can be restored as required when the search string is changed or deleted. It expects the data to be saved inside the dghProp["saved data"] custom property of your datagrid. This property is set by a "set prop dghProp" handler in the script of your data grid (It is a handler in the group “your data grid”). Depending on your application you may wish to save this elsewhere. ## Uncomment the following line for filtering the data grid display. ##*/ -- DGH_Search_FilterDGByIndexes pTheDGName, tTheIndexFound /* Hiliting found text The following line of code enables the hiliting of the found text strings. If you have enabled row filtering (by uncommenting the previous line) you may wish to turn off the hiliting. To do this, simply comment out the following line. */ set the dghProp["text to find"] of grp pTheDGName to pTheString end if DGH_Search_RowsCount pTheDGName, tTheIndexFound end DGH_Search_Launch
Please note the warning regarding the saved dgData.
This line in the "dghProp" handler in the script of the data grid group:
set the dgData of me to the dghProp["saved data"] of me
saves the dgData of your data grid to a special dgh property named "saved data", so that the original data can be restored at anytime (such as when the “find” string is changed).
You may wish to save the data to another place, to limit risks.
Testing The Search Script
Once the line DGH_Search_FilterDGByIndexes... is uncommented, testing the search field will filter the rows inside the data grid, by only displaying the found ones.
And if the search field content changes again, the rows are filtered accordingly.
Disabling The Found Text Highlighted Feature
You can disable the highlighting of the found text by commenting this line in the DGH_Search_Launch handler (See full script above):
set the dghProp["text to find"] of grp pTheDGName to pTheString
So changing the search text to trigger our modification, we now have the found row displayed, but without the found text marked in color.