Developer

Complex Table Drop Down

The complex table drop down field edit type displays a drop down list of unique values from a defined complex table field. This screen field edit type is normally used in a cascade control series, allowing users to drill down through records within the table that have a parent-child relationship.

A cascade is a series of multiple fields all displaying the same complex table. Each cascade field displays a different complex table field. The records displayed in a field are the child records to the selected record in the field before it in the cascade. The parent-child relationship is determined by the structure of the indexes for the complex table being displayed.

The overall behavior of a cascade forces an Agentry Client user to make a selection in the first field in the cascade, which is a top-level parent record in the complex table. The next field in the cascade is not enabled until this selection is made. At this point, the values listed in the second field are only those complex table records that are children to the record selected in the first screen field. This behavior repeats for each field in the cascade.

Defining such a cascade requires that the complex table displayed by these fields have the needed parent-child indexes defined. Each cascade screen field must have a matching child table index at the same level. Keep in mind:
  • Agentry Editor filters the list of available indexes when the designer selects an index with a parent.

  • Agentry Client also filters the available indexes displayed at runtime to only include valid selections.

Alternatively, if you chose to index by rule, the valid choices are determined dynamically at runtime. Checking an index in the filtering list in the editor definitions never overrides when the client has selected an invalid index. Instead, the opposite works: unchecking an index causes the client to not display an otherwise valid index selection.

Both the complex table drop down, and complex table list field edit types support cascade behavior. Fields of both types may used in the same cascade series of fields on a given detail screen.

Cascade Example

The Complex Table Search Control works with both top level, and non-top level indexes. This enables you to use the control as shown in the following scenario.

You have defined a complex table with the following fields and indexes:
Fields
   ID
   State
   County
   City
Indexes
   ID – unique, parent = none
   State – non-unique, parent = none
   County – non-unique, parent = State
   City – non-unique, parent = County
Use multiple Complex Table Search controls to drill down to a unique city value.
CTS – State
   Search Index – State
   Parent Value – N/A
   Return Field – State
CTS – County
   Search Index – County
   Parent Value – Rule - State
   Return Field – County
CTS – City
   Search Index – City
   Parent Value – Rule - County
   Return Field – City

Rules can be set to a concatenated list for third tier values. In this example, the Parent Value could be set to a rule that would contain “@sum ‘my_state @newline ‘my_county”. This would provide the necessary parent values for the City index to search correctly.

Complex Table Search Dialog

As an option to displaying the values of a complex table, the Complex Table Search Dialog field type can display a complex table search dialog. Within this dialog the records of the complex table are listed within multiple columns, one for each complex table field. The records displayed in this dialog are dependent on the selections made in previous fields in the cascade control series.

Definable behaviors in this dialog include options to specify:
  • Indexes on which the user can search

  • Specific complex table fields to display in the list

Keep in mind that only indexes that have the same parent with the selected table index are available. In order to have all indexes available for selection, you must choose a top-level index.

Complex Table Scanning Input

This field edit type also supports scanning as input. When this behavior is enabled, the value scanned in must be one that can return a record using the index specified for the screen field.

Complex Table Drop Down Attributes

Following are the attributes specific to fields with an edit type of complex table drop down. These are in addition to the common field attributes:
  • Complex Table: Specifies the complex table the field is to display. In a cascade it is possible for each field to display a different complex table, provided the values selected in one can be used to search the next. This is not the recommended method for using cascades, as it is more efficient to use a single complex table for all cascade fields.
  • Table Index: Specifies the complex table index that should be used to search that table. For the first field in a cascade, this index should be the top-level index, that is, an index that does not have a parent index. For subsequent cascade fields, the selected index should be the child index to the index selected in the field that precedes it in the cascade.
  • Cascade Parent: References another screen field on the same detail screen to use as the cascade parent for the field. If left set to Auto, the cascade is determined based on the selected Table Index. The field whose Table Index is set to the parent index of the selected Table Index for the field is treated as the cascade parent screen field. If the proper index structure is in place in the complex table, the cascade parent can be left set to auto.
  • Display Field: Specifies the complex table field to display for the table records. Leaving this attribute set to Auto displays the field upon which the index selected in Table Index is defined. This is the recommended selection for this attribute. Only unique values of this field will be listed.
  • Return Field: Contains the complex table field to return from the selected record. When left set to Auto, the return field is the field upon which the index selected in Table Index is defined. This is the recommended selection for this attribute, as this value will be the one passed to the next field in the cascade.
  • Selection Method: Specifies how the records of the complex table being displayed by the screen field are displayed to the user. Following are the options for this attribute:
    • Always Drop Down Menu - Always list the records of the complex table in a drop down list.
    • Always Open Dialog - Always list the records in a popup dialog.
    • Always Open Dialog with Search - Always open a complex table search list dialog that provides the user with the ability to enter search text to locate the desired record. This dialog lists all fields, or only those selected in the Search Dialog Indexes list, for each record in the complex table.
    • Open Dialog if Needed - Allows to the specification of record threshold. For this option, the default is to display the records in a drop down list. If the number of records to list exceeds the defined threshold, a popup dialog is displayed listing the records in a list box control.
  • Open Threshold: This attribute can be set only of the Selection Method is set to Open Dialog if Needed. This attribute can be set to the Default, which will vary from one client device to another, or to a specific number of records. When the Open Threshold is exceeded, the popup dialog is displayed, listing the records from the table.
  • Scanning: This attribute, when set to true, enables the client device’s scanner (if present). The user can scan a barcode value, which will be used to search the complex table by that value using the defined Table Index. If a single matching record is found, that will be the selection for the field. This attribute only has an impact if the client device has a scanner, and if the parent detail screen is used by a scanner platform.
  • Handle Special Value By: This attribute is available only if a special value has been defined for the screen field. This attribute specifies what to do when the cascade parent value changes. You can define the field to then set itself back to the special value, change to the default text of “Please select,” or to change to the “Please select text” only if the current selection is not the special value.

Search Dialog Indexes

For detail screen fields defined with an edit type of complex table drop down, there are two lists of items shown in the properties view of the Editor. The first is the Search Dialog Indexes tab. Listed in this tab is one item for each top-level index defined in the complex table the screen field is displaying. For complex table drop down lists the selected search indexes only affects behavior when the Selection Method attribute is set to “Always Open Dialog with Search.” Each item contains a check box which, when selected, displays that index to the user as one that can be searched on. Those indexes not checked in this list are not displayed to the user.

Search Dialog Fields

For detail screen fields defined with an edit type of complex table drop down, there are two lists of items shown in the Properties view of the Editor. The second is the Search Dialog Fields tab. Listed in this tab is one item for each field defined in the complex table being displayed by the screen field. For complex table drop down lists the selected fields only affects behavior when the Selection Method attribute is set to “Always Open Dialog with Search.” Each item contains a check box which, when selected, displays that field to the user in the list of records. Fields that are not selected are not be shown to the user.