Working with Lists

Documentation home

See also: How to use Dynamic Lists, How to use Static Lists, Working with Databases

Any form field or table column in an Ebase Xi form can be associated with a list by configuring the list properties of the field/column. The list is then displayed to the user by adding the field/column to a page. 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 Xi 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 workspace. 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. Here are examples using a Javascript script:

// create simple list with three entries

var list1 = ["Line 1", "Line 2", "Line 3"];

fields.Field1.createCustomList(list1);

// create list with both displayed and return values

var list2 = fields.Field1.createCustomList();

list2.add("Display Value 1", "Returned value 1");

list2.add("Display Value 2", "Returned value 2");

list2.add("Display Value 3", "Returned value 3");

Common aspects of list behaviour

The field or column with which the list is associated must have a display type that enables the list to be displayed i.e. dropdown, radio button or checkbox. If not, the list won’t be shown.

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 a Dynamic List 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 displayed value is shown.

The text 'Please Select' or its equivalent in other languages represents a null value and by default appears at the top of each list. This text can be changed or suppressed for individual lists by configuring the Header text options in the list tab of the field’s properties. The default header text is taken from system text 21 – if you would like to change this text for all lists, edit this text.