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:

1. 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)
2. 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.