Search forms

Overview

A Search Form exposes several Search Parameters. When the user submits a search form, a search query is issued, using these parameters as bind values.

Search Forms are used to filter data in the business views or to search for records in the global search.

A search form exposes several Search Parameters to look for records in an entity. When the user submits the search form, a Search Query is issued, using these parameters as bind values.

Create search forms

To create a search form:

  1. Right-click the Search Forms node under an entity and select Add Search Form…. The Create New Search Form wizard opens.

  2. In the Create New Search Form wizard, enter the following values:

    • Name: Internal name of the object.

    • Label: User-friendly label in this search form.

    • Description: Description of this search form.

  3. Click Finish to close the wizard. The Search Form editor opens.

  4. Define a Search Tip text that will be displayed in the search form.

  5. Add a search parameter:

    1. In the Search Parameters table, click the Add Search Parameter button. The Create New Search Parameter wizard opens.

    2. In the Create New Search Parameter wizard, enter the following values:

      • Name: Internal name of the object.

      • Binding: You use this binding string in the search form SemQL query condition to refer to this parameter. Note that as the Auto Fill box is checked, the Binding is automatically filled in. Modifying the binding is optional.

      • Label: User-friendly label for this search parameter. Note that as the Auto Fill box is checked, the Label is automatically filled in. Modifying this label is optional.

      • Use Type, Length, Scale and Precision to define the logical data type of this parameter.

    3. Click Finish to close the wizard. The parameter appears in the Search Parameters table.

      • To edit a search parameter: Select the Properties view and then select the search parameter in the table. The Properties view shows all its properties, including the Name and Definition as well as the Search parameters display properties.

      • To remove a search parameter, select the search parameter in the search parameters table, click the Delete button and then confirm the deletion.

    4. Use the Properties view to configure the search parameter.

  6. Repeat the previous step to create all your search parameters.

  7. Reorder search parameters in the table using the Move Up and Move Down buttons.

  8. Create a SemQL Condition for the search query by clicking the edit expression button Edit Expression button to open the SemQL Editor. Note that the SemQL editor displays the search form parameters bindings in the Variables section.

New search forms designed for an entity are not immediately available in the business views or applications using that entity. You must define a Search Configuration in the Business views to enable or disable both the built-in search types and your search forms.

Search parameters display properties

The Display Type of a search parameter defines the component used to display this parameter in the search form. A Display Type is optionally configured through display properties.

The display type available for a search parameter depends on its logical data type. For example, the Date Picker display type is available only for a DateTime search parameter.

The display types are listed below with their properties:

  • Text Field: Simple text field. This type is available for all logical data types.

  • Checkbox: Simple checkbox. This type is available for the Boolean logical data type. Its default value is null.

  • Date Picker: Date (and time, for a timestamp datatype) selector. This display type is available for the Date and Timestamp logical types.

  • Drop Down List: Selectable list of elements. This display type is typically used to select a search parameter value from a list of values. It is configured using the following options:

    • Display Format: Defines whether the label and/or code of the list of values should be displayed.

    • Sort Order: Defines if the list of values should be sorted by the code or label.

  • Value Picker: Auto-complete component used to select filtered values from a given entity of the model. It is configured using the following options:

    • Lookup Entity: Entity from which the values are selected.

    • Filter Expression: SemQL expression used to filter the entity data. This expression can use other search parameters' values.

    • Bound Select Expression: SemQL expression defining the value returned by a value picker selection.

    • Primary Text Expression: SemQL expression defining the value displayed in the auto-complete items' first line.

    • Secondary Text Expression: SemQL expression defining the value displayed in the auto-complete items' second line.

    • Use Distinct: Check this option to only display distinct values in the auto-complete component.

    • Display Count: Check this option to display the count of records for each distinct value in the auto-complete. This option is available if Use Distinct is selected

    • Sort By Count: If Display Count is selected, this option allows sorting by ascending or descending record count. Note that if a value matches exactly the user input, it always appears first in the list.

    • Default Sort Expression: If Use Distinct is not selected, this SemQL expression defines the sort order of the records in the auto-complete. Note that if a value matches exactly the user input, it always appears first in the list.

Search form SemQL condition

The SemQL Condition defined for the search form can use attributes from the search entity as well as attributes from related (parent or child) entities. Refer to a search parameter with its Binding prefixed by a colon :.

For example, if a search form on the Customers entity has one parameter labeled Searched Name (binding: SEARCHED_NAME), the following SemQL condition filters customers by their name.

CustomerName like '%' || :SEARCHED_NAME ||  '%'

If we add to this form a second parameter labeled Has Influencer Contact (Binding: HAS_INFLUENCER_CONTACT), the following SemQL condition filters customers by their name and possibly, depending on the fact that they have one or more contacts with IsInfluencer = 1

CustomerName like '%' || :SEARCHED_NAME ||  '%'
and
( :HAS_INFLUENCER_CONTACT is null
  or
  :HAS_INFLUENCER_CONTACT = '0'
  or
  any Contacts have (IsInfluencer = '1')
)
Although it appears an unselected checkbox in the original search form state, a boolean parameter using a Checkbox display type has a null value by default. It takes the value 1 (true) or 0 (false) only when the user selects or unselects the checkbox. You should take into account that original state in the SemQL condition. The example above uses the original checkbox state (null) as an equivalent of a false (0) value for the HAS_INFLUENCER_CONTACT search parameter.