skip to main content
OpenEdge Development: AppBuilder
Data-Access Objects : SmartFilters
The query you build into your SDO might return thousands—or even millions—of records. A return of such size can totally overwhelm users, causing them to fervently wish for a way to further subset the data stream. AppBuilder offers an ADM SmartObject to deal with that problem: the SmartFilter.
The SmartFilter provides a query‑by‑form (QBF) interface to the data stream supplied by your SDO. Using the SmartFilter, the user of your application can narrow the query as much as desired, possibly causing the query to return only a few records or even no records at all. Being able to focus the query more tightly can be very convenient for the user.
As seen by the user, the SmartFilter is rather simple. Each filterable field is represented by one or two editable fields representing a value and a comparison operator, as shown:
The user controls the object’s behavior using the following buttons:
*Apply filter — Activates the filter immediately, reducing the size of the data stream. To clear the effect of a filter, the user must click Blank and then Apply.
*Blank — Clears all editable fields and resets the operators (if visible) to their default states, ready for the next setup.
*Reset — Restores the most recent filter expressions. Does not clear the fields.
The SmartFilter is supplied as a pre‑compiled master rather than as a template.
To include an instance of the SmartFilter in your application:
1. Click on SmartFilter in the Object Palette. There might be a short pause while AppBuilder creates the instance.
2. Position the cursor over the workspace and click to place the instance.
3. If you previously placed an SDO, AppBuilder now opens an Advisor window offering to create a Filter link to it. Unless you have reason not to do so, accept the offer:
4. Inspect the properties for this SmartFilter and change any that do not meet your needs. See the “Configuring SmartFilter properties” section for information about how to do that.
5. When you have finished making changes, click OK to dismiss the properties dialog box.
6. Click the object to select it. Drag the handles to position and size the object to suit your layout. Your SmartFilter is now ready for use.
Configuring SmartFilter properties
There are a number of changes you can make to the appearance and behavior of a SmartFilter instance through the Properties dialog box. This section discusses the options available to you.
To open the dialog box, right-click on the instance and choose Properties. The dialog box appears as shown:
This area identifies the data source, and the fields to be filtered:
*For your convenience, if you place the SmartFilter object into your workspace after you place the SDO, AppBuilder automatically fills in the Target field for you. This is generally the best way to do it.
But if you place the SmartFilter instance first, you can still fully configure it. Click the Browse button and, when the Choose dialog box opens, select the appropriate SDO and click OK. The object filename immediately appears in the Target field, and a list of database fields supplied by that master populates the Fields field. Note that you are not in any way attaching that data source at this point; you have merely identified it so that you can configure your SmartFilter.
*By default, none of the fields supplied by the SDO are filterable.
Click Edit Field List and select the fields to make available for filtering. They will appear in the Fields list. If you change your mind about one of the fields, simply select it and click Remove. Removing the field from the filterable list has no effect on the data stream or the SmartObject assigned to display the data. To restore a field to the filterable list, click Edit Field List and add it back.
Note that performance might be unacceptably low if the number of records is large and you allow the user to filter on fields that are not indexed.
You can define the amount of control the user has over the filter operation by setting the Style value. The Style you choose applies to all fields unless you modify the setting for a particular field. The possible values for Style are:
*Implicit — Choosing this option removes the relationship operator from the user’s control. The user still selects the value against which the filter tests, but cannot change the nature of the test (equality, inequality, etc.). You set the type of test at design time using the related combo box.
By default, the operation you choose in the combo box is ignored for character string fields. Character strings undergo a BEGINS test regardless of the setting in the combo box. If you want character strings to be tested using the operator you set in the combo box, uncheck the BEGINS box in the String Operator frame (below the Style radio buttons).
When Style is set to Implicit, you can set individual fields to be Ranges, instead. See the View as Range Fields option in the “Field Properties” section.
*Explicit — The default Style. Choosing this style allows the user to select the type of test on a per‑field basis. The user selects the operator from a combo box (default) or by setting a radio button; see the “Operator View As” section.
Because BEGINS can be applied on a per‑field basis for character fields (it appears in their list of operator choices), the global BEGINS option is disabled when Style is set to Explicit.
You can set individual fields to be ranges. See the View as Range Fields option in the “Field Properties” section.
*Range — Choosing this style causes the SmartFilter to display two fill‑ins for each field, representing the upper and lower bounds of a range. The user types in the limiting values, which are considered inclusive. For example, entering c as the lower bound and e as the upper, for a CHARACTER field, will return all records where the value for that field is in the range c* through e, inclusive. Note that while e itself would be included, e* is not. Similarly, entering bounds of 10 and 100 for an INTEGER field would return all records where the value of that field is in the range 10 - 100, inclusive.
When Style is set to Range, you can set individual fields to be Explicit, instead. See the Explicit Operator option in the “Field Properties” section.
*Inline — Choosing this style requires that the user enter the comparison operator along with the value. For example, to test for INTEGER values over 10, the user must type in
> 10.
If the user enters a value without an operator, for example 10 rather than >10, the SmartFilter will presume the intended operator is EQUALS. The only exception is if the field is of type CHARACTER and the BEGINS check box is set. In that case the SmartFilter will perform the BEGINS test instead.
String Operators
When these check boxes are enabled, setting them overrides any conflicting setting in Style:
*BEGINS — When checked, the SmartFilter will perform a BEGINS test against CHARACTER fields
*CONTAINS — If the field being filtered is word‑indexed, the SmartFilter will represent the field as an editor widget sized according to the Number of Lines in Editors setting in the Size & Position section.
Operator View As
By default, the SmartFilter lists the operators for Explicit fields in a combo box. You can force the options to be listed as radio buttons instead. To choose a representation, set the appropriate radio button.
Size & Position
Size & Position allows you to set the following visual characteristics of the SmartFilter instance:
*Default Field Widths — Set the displayed width of the editable portion of the filter fields. You can set the width separately for non‑CHARACTER fields, and can override these settings on a per-field basis in the Field Properties section. The width you set here only affects the visible portion of the field, and it has no effect outside the SmartFilter itself.
*Field Position — You can control where the editable portion of the field starts. To minimize the amount of space the filter takes up in the X dimension, set this value to the character count of the longest field label, plus two. For example, if your longest label is “Postal-Code:”, set the value to 14. If you use a smaller number, the field will hide the right end of one or more labels. If you use a larger number, both the fields and their labels will move to the right within the SmartFilter’s frame.
*Number of Lines in Editors — If the SmartFilter represents any field as an editor widget, this value is the number of lines that will be displayed. If you set this value to 1, the widget will display with the same height as a fill-in, and it will have no word‑wrapping. If you set the value to 2 or more, the field will have word‑wrapping and a vertical scroll bar.
Field Properties
Each filterable field has several default properties that you can change. Note that such changes have no effect on the database, the data stream, or how the data‑display object treats the field. All changes are local to the SmartFilter.
To begin, select the field whose properties you wish to change:
*To change the label that identifies the field, uncheck the Filter Target box and type in the new text for the label. By default, the label is inherited from the field name in the schema.
*To change the field width, uncheck the Use Default box and type in the new value in character units. The default value is taken from the field definition in the schema.
*You can add text for a Tooltip identification by typing it in that field.
*If you plan to provide context‑sensitive help, enter a unique INTEGER value for this field in the Help ID fill‑in.
*The filter operators (equals, greater than, etc.) all refer to a single value. To select instead for values that fall within a certain range, check the box View as Range Fields. This option is available only when Style is Implicit or Explicit.
When View as Range Fields is checked, a second editable field appears in place of the operators list.
*You can override the Range style on a per‑field basis by setting the Explicit Operator box. The user will then see a single fill‑in field instead of two, and be able to choose the comparison operator from a combo box.