Working with Lists

Documentation home

See also:

How to use Dynamic Lists

How to use Static Lists

Working with Databases

Any form field in an Ebase form can be associated with a list by configuring the list properties of a field. Three types of list are supported:

• A dynamic list represents a list of values that are extracted dynamically from a database at runtime. Examples could include a list of customer names, or a list of cities, etc. These lists can be linked, e.g. a list of countries, followed by a list of regions, followed by a list of cities. As each value is selected, the next list is populated. The database providing the list values can be any database to which the Ebase system has access. The list is prepared when the page is prepared for display.

• A static list is a list of values stored within the Ebase repository database. As the name implies, static lists are intended to be used when the list values do not change very often. Examples might be TITLE consisting of values Mr, Miss, Mrs, Dr, etc, or CONTACT_CATEGORY consisting of values Customer, Vendor, Partner, etc. An important aspect of static lists is that the values can be displayed in any language. The list is prepared when the first reference to the list is made, and it is cached in memory thereafter.

• A custom list is a list of values that is created dynamically using a script program.

Some aspects of behaviour are shared by all types of list (see below), but there are also some differences.

Both dynamic lists and static lists are stand-alone elements within the Ebase system and, once created, can be used by all fields in all forms.

Shared aspects of list behaviour

Each list entry can optionally contain both a displayed value and a returned value. This allows you to display a descriptive name while retaining a key value e.g. if displaying employee details, the department_id field might contain a numeric id but be displayed as the descriptive department name. With dynamic lists, the displayed and returned columns are configured when you map the list to a field.

When a field associated with a list is display only, the returned value is always displayed.

When a field associated with a list is editable (i.e. not display only), the list behaves differently depending on the display type of form field with which it is associated. When the display type supports multiple values, i.e. a dropdown list, radio buttons or checkboxes, the list operates in list mode and a list of values is presented to the user for selection; this is normally what is required. However, when a list is associated with other types of field, usually a text entry field, the list operates in validation mode, and will then validate the data entered by the user against the list. This mode is intended to be used for large lists where it is not practical to download all the list values.

When operating in validation mode, the list can be customised to control its behaviour when a not found condition occurs. The available options include:

• issue a standard error message
• issue a specific error message
• handle the condition in a script by checking the $FOUND system variable

When operating in list mode, the text 'Please Select' or its equivalent in other languages will normally appear at the top of each list. This text can be changed or suppressed by configuring the list properties for the field. If you check the Set Field with Single List Value checkbox on the form field properties, list tab, then this text will be removed.