Component: Search Criteria
The search criteria component displays one or more fields from multiple ReST API requests which can be used to search over large data sets.
The search criteria component typically works with another component such as the grid, to allow the end-user to add multiple filter fields which are then applied to return only matching data records.
This is an example of a search criteria component showing 3 lookup fields which when applied, displays matching data in the grid.
In this example, each of the 3 fields is populated from its own ReST API data source request.
The search criteria component has the following features:
Multiple Fields
Use the 'plus' button to the right of the And button to add fields to the component. Use the x button to the right to remove each field.
AND
This component does not attempt to be too complicated to use so all fields are 'anded' meaning that only records which match all fields are returned.
Field Types
Fields can be lookups, text, numbers.
Apply
This button is used to send the selected search criteria to the attached component to display the matching data.
Persistence
Every time you re-open this form, the search criteria component remembers your search from last time.
Search Criteria components should be dragged from the form designer toolbox into the form for lookup forms only. Once a search criteria component is on the form being designed, click it to open up the component properties modal popup dialogue.
The form has 5 tabs, and an Apply button to save the changes and close the form, and a Cancel button to close the form without saving. Note that saving a component must be followed by saving the form design in order to persist the settings.
The Details, Styles, Data Sources and Developer Configuration tabs are discussed in the Components section. The Search Criteria tab is specific to this component.
Data Sources
The data sources tab is similar to that discussed in the Components section however it is worth pointing out that this component will have multiple ReST API data source requests, one for each field, but also a master.
In this example, we can see that the first 3 data source requests are for specific fields, whereas the 4th is for the master data set i.e. the one which is searched using the filtered fields.
Search Criteria
This tab allows the search criteria specific behaviour to be configured.
There are 2 left docked sub-tabs.
Data Sources
Choose the master data source request from which to obtain a list of fields to search. Each field can be configured to read a list of available lookups from another data source request.
Multiple data sources may have been configured, usually one for each field, but also a master request.
Master Request
This drop-down combo has the list of all the data source requests added in the Data Sources tab.
This master request should be selected as this then allows each of the other fields to map to fields in the master data set.
The Refresh button will read the selected master request and replace the existing field list.
Master Fields
This shows the list of all fields from the master ReST API data source request.
The field order can be manipulated by using the buttons to the left of the list to move up, move down, or indeed delete the field from the list. It is often better to simply hide fields rather than delete them.
The field properties are as follows:
Name
This is the name of the field from the ReST API request
Type
Usually a string or a number, but sometimes an image URL or Base64 image.
Format
Most fields will display as expected, however some may need to be specially formatted e.g. currency, dates etc..
Caption
This is the field header text. Often field names from ReST API's can be cryptic so setting a human legible caption is recommended.
Visible
Whether the field is visible or not
Lookup
This shows whether any ReST API data source requests have been assigned to this lookup field. The Assign button is visible when none have been assigned and the Remove button is visible otherwise.
Data Field
Visible when a lookup is assigned. This is the data field from the ReST API request which is linked to the key identifier.
Display Field
Visible when a lookup is assigned. This is the data field from the ReST API request which is human recognisable.
Custom Variable
Visible when a lookup is assigned. This is the custom variable populated with the data field value. It is needed by connected components to filter data.
Sort Alphabetically
Visible when a lookup is assigned. Sorts the display field in alphabetical order.
Sample Values
This is a sample of the values read from the ReST API request to help configure the field.
An example of a Lookup is this:
This shows that the field is a lookup linked to a ReST API data source request, linked to an identifier field, using a different sorted field to display and linked to a custom variable.
At run-time this specific field in this component shows the field name using the Caption property and shows a drop down list of Display Field values.
When the filter is applied, it is the field Name value which is passed to the connected component.
Events
This sub-tab is used to trigger dependent components. The Apply button applies the selected search criteria to any linked components by triggering the population event. This functionality can also be used to automatically populate dependent components after loading the previously persisted search criteria.
Automatically Trigger Dependent Components
Only the dependent components need to know who we are, not the other way around. This means that the search criteria component is not concerned with what other components are notified when the Apply button is clicked.
For example, a Grid component may be located on the same form, and it will be configured to be populated only when the this specific Search Criteria component sends it a filter when the user clicks the Apply button.
Last updated