List Selection
The list selection field edit type displays a drop down list of values, the source of which may be an object collection, data table, or complex table. This list is treated as a temporary data table created at run time. Part of the definition of this edit type is to specify the values to be treated as the code and value fields for each record. Definable behaviors include whether to display the code, value, or both for each item listed. The code field is always the value returned from the selected item in the list.
A field with this edit type is displayed as a drop down list on the detail screen. If the number of records displayed in the list is large, a popup dialog will displayed when the user selects the field.
To use this edit type, either an object collection property or complex table is selected as the source for the items listed. Within this selected source two data members (object properties or complex table fields) are selected as the code and value for the records in the temporary data table.
Another aspect of this edit types behavior is the option to define an include rule. If used, this rule will be evaluated for each object or record in the defined source and only those items for which the rule returns true will be listed in the field. Note that this rule evaluation should be made as efficient as is possible when working with complex tables with large numbers of records.
- Source: This attribute specifies the source object collection property or complex table for the field. The collection or complex table may be returned via a rule, or it may selected from the target browser. Within the target browser, options exist for selecting object instances or a range of complex table records via a rule. Note that this is separate from using an include rule, which is another attribute to the field type. In most situations simply the object collection or complex table is selected here. It may be desirable for complex tables to return a range of records based on a table index. In this case the search value is provided in the target browser, which may come from an object property or a rule. Specifying a search value for the complex table to reduce the number of records for the field can significantly reduce the number of evaluations needed for the include rule, if one is used.
- Include: The Include attribute can reference a rule definition that will filter the records listed to the user. This rule is evaluated in the context of each data instance (object or complex table record) returned by the Source attribute and is expected to return a Boolean value. Only those data instances for which this rule returns true will be listed in the field. If no Include rule is selected, all instances of the selected source will be listed.
- Key: This attribute specifies the data definition within the Source instances to be used as the code (also known as the Key) field for each record in the temporary data table. This will either be an object property or complex table field, depending on the selected source.
- Value: This attribute specifies the data definition within the Source instances to be used as the value field for each record in the temporary data table. This will be either an object property or complex table field, depending on the selected source.
- Sort By: This attribute allows you to sort the values listed in the drop down list by one of several options: Code, which is the code field in each table record; Value, which is the value field in each record; Displayed Text, which is the text displayed for each record in the field; and Order in Data Table, which is the order in which the records are listed in the data table itself.
- Sort Order: This attribute specifies whether the records displayed are sorted in ascending or descending order. This is a string sort.
- Display Type: This attribute specifies which fields from the data table records should be displayed in the drop down list. The options are: Code, meaning the code field in each table record; Value, which displays the value field from each record; Code - Value, which displays both fields from each record, separating them with a hyphen; and Format Text, which allows you to specify format strings to format the values displayed in the list for each record.
- Format Text: If the Display Type attribute is set to “Format Text” this attribute will be enabled. Format strings can then be entered in this attribute to format each record from the data table. The valid format strings for this field are %code, %value and %position. This last will display the position number of each record as stored in the data table. This last option is used mostly for testing purposes and is generally not found in the production version of an application. This attribute can also contain any other printable characters, excluding tabs and carriage returns, to format the display of the table’s records.
- Editable - Allow User-Entered Values: This attribute specifies whether or not the user can manually enter values not found in the source of the list. When set users will be able to either select an item from the list or manually enter a text value in the field. When not set the users will be required to select from the items in the list. Note that if the field is set to read-only, this attribute should still be set if the field has an update rule defined, and if that rule can return a value not found in the data source for this field.
- Define separate display type for popup dialog: This attribute allows you to display the records from the data table differently in the popup dialog vs. the drop down list for the field. If set to false, the display and format attributes listed above will also affect the popup dialog. If set to true, the attributes listed next will provide separate display behaviors for the popup dialog.
- Display Type (Popup Dialog): The options for this attribute are the same as the Display Type options listed previously. The option selected here will impact the appearance and behavior of the popup dialog displayed for larger data tables.
- Format Text (Popup Dialog): The format strings for this attribute are the same as the Format Text options listed previously. The format text entered here will impact the appearance and behavior of the popup dialog displayed for large data tables.