The Query by Example component allows a search interface to be created, which embedded queries can use to constrain which records they display.
This allows
The overall configuration is to:
- Add a Query by Example component to the site and configure it with the various fields to display.
- Add a Query component to the site, and configure this to display the records
- Embed both the Query by Example and the Query on a Page, and configure the Query embed to listen for the changes the user makes in the Query by Example form.
Note: unlike other search tools in the system, the Query by Example component does not need to be linked to a particular Query (though the values it offers can be driven from queries if needed)
The Query by Example component consists of a single surface. The configuration interface consists of two columns, with the surface in a tree on the left, and a preview of the surface output on the right.
To edit the surface:
Double click the Query by Example node in the tree, or right click it and select Edit
When editing the surface the usual set of embeddable objects are available. Additionally there are two specific to this surface:
Field
This allows a Query by Example field to be rendered (a textbox, dropdown, date picker etc).
Submit Button
This allows a Submit Button to be rendered. The use of this button is optional, as the Query by Example can be configured to submit automatically whenever a change is made.
The Field embed
One or more Field embeds can be embedded on a Query by Example surface
Each embed needs to be configured through its embed dialog:
Parameter name (required)
A text string, lower case with no spaces.
This will be used by Queries in the Record Criteria to identify the field.
Field type
A choice of:
Check Box List
Date
Drop Down List
Number
Radio Button Group
Text
Yes / No / Either
Allowed values
Shown only where the Field Type provides a selection of options to choose from, ie is set to:
Check Box List
Drop Down List
Radio Button Group
For these Field Types, the Allowed value field is required, otherwise no options will be listed for the user to select from.
The sub dialog allows this to be configured to show values from either of a:
Table
Select the Table, and the Field
All records in the Table will be provided as allowed values.
If only a subset of records is to be allowed, choose Query
Query
Select a Query, and the Field
In the Query dialog, the Records tab allows criteria to be selected to constrain the subset of records allowed.
Note: the criteria can refer to Named Parameters which match the Parameter Name of other Query by Example fields in the surface, therefore allowing the allowed selection for one field to be affected by the user's chosen value in another Query by Example field.
For this to work, the Query by Example embed (ie where the Query by Example surface is embedded on the Page must be configured to include in its "React to Transitions" a Channel that that the Query by Example is sending on (ie as specified in the "Channels" field of the same dialog)
Example: this can be used in an ecommerce catalog where the user can narrow the list of products by several aspects, say Brand and Size, such that when they select a Brand, the list of Sizes offered is restricted to sizes supplied by that Brand, and conversely, if a Size is selected, the list of Brands is constrained to those offering products in that size.
Default value
This sub dialog allows the default value for the field to be set.
If this is left unconfigured:
The field will be left blank.
If the field type is such that a set of options are provided, none will be selected.
Note that when a field is left bank or no options are selected, in the Query by Example context this generally means the user does not wish this field to be considered by the criteria restricting records. Accordingly 'nothing selected' will be effectively the same as 'all selected'.
The Sub Dialog provides three sources of value to define the Default values:
Explicit
For when the set of Default values is to be set to a constant subset (ie not varying depending on context)
A picker is shown allowing one (for Radio Buttons or Drop Down Lists) or more than one (for Check Box Lists) value to be selected.
Where appropriate a default of "Unselected" or "None" may also be chosen.
Parameter
For when the Default should be set directly to the value of a Parameter
Query Field
Select a Query, and the Field
In the Query dialog, the Records tab allows criteria to be selected to constrain the subset of records allowed.
Note: the criteria can refer to Named Parameters which match the Parameter Name of other Query by Example fields in the surface, therefore allowing the allowed selection for one field to be affected by the user's chosen value in another Query by Example field.
For this to work:
- The Query by Example embed (ie where the Query by Example surface is embedded on the Page must be configured to include in its "React to Transitions" a Channel that that the Query by Example is sending on (ie as specified in the "Channels" field of the same dialog)
- The "Re-apply on transition" checkbox on the field dialog must be checked, and optionally set to listen to the Channel the QbE is sending on.
