Concepts: choice lists

A choice list is a collection of predefined property values which can be used to present users with a list of values from which to choose. Using a choice list:

A choice list is an object that contains a list of choices. A good example for using choice list would be for something like the US states and the two-letter state codes, where the choices are not expected to change. Choices consist of a display value and an actual value which is persisted in the database.

To make a choice list usable, you must assign it to a property template. See Create a choice list which includes the requirement to assign the new choice list to a property template for more information. Enterprise Manager will not allow you to delete the choice list object as long as it is associated with a property template. One choice list can be used by many properties. A choice list cannot be used within another choice list.

Content Engine installations using a case sensitive database can distinguish between case sensitive items in a choice list. Using a database, an item in a choice list could be set to "ITEM1" while another could be set to "item1", and the two would be successfully handled and queried.

NOTE  The Choice list size site preference determines the maximum number of choice list elements to display. A Workplace XT or Workplace user can see no more than the pre-set number of choice list elements, with no indication that more may exist.

To provide users with quick, easy selections when they enter data, you should follow these guidelines:

Using Enterprise Manager to create choice lists

The Create a Choice List wizard:

The Create a Property Template wizard:

Enterprise Manager provides a way that you can localize a choice list's display names.

Choice list security

Choice lists have their own security. By default, the Choice List Wizard automatically assigns to the new choice list the security defined on the Default Instance Security tab of the Choice List class, which is initially the same security as the object store:

To change these default settings, you can either change the Default Instance Security of the Choice List class before creating the new choice list (the Choice List class is not subclassable), or you can directly edit the choice list's security by opening its property sheet, clicking the Security tab, and directly assigning security. For example, if you had two groups of users with basic View access to the object store, you could deny the right of one of the groups to see a particular choice list.

Cannot import duplicate choice lists

As a general rule, you cannot import a choice list (or any other class of object) if the object store already has that exact same object; that is, if it has the same GUID or Name. As explained in the topic Importing an XML file into an object store the Enterprise Manager's Import Helper checks for duplicate components and will not overwrite an existing object with a duplicate. When encountering a duplicate object, the Import Helper records the duplicate entry as an error in a log file and continues to import objects that haven't already been added to the object store.

Example - groups and items

The following example shows the property sheet of a choice list named "Fish" which contains two groups, each containing three items. An application could be designed so that the user would first choose the group, and then be offered to choose only the items within that group.

When displayed by Enterprise Manager, each item consists first of the DisplayName Property (a simple localizable string property), followed in parentheses by the Value Property (the data type of which is determined by the data type, string or integer, of the choice list).

Example - uniqueness of values

Enterprise Manager enforces uniqueness of group names within a single choice list, and also uniqueness of display names within a single group. However, it does not enforce the uniqueness of item values. (This is by design, as there are use cases where uniqueness is not desirable.) Therefore, you should understand the possible consequences of having duplicate item values. Consider the following example:

This example shows a choice list named "Color choices" which contains duplicate item values: there is a blue car and a blue boat. After a choice is made, you will not be able to tell whether it was the blue car or the blue boat that was selected. To avoid this uncertainty, you could add more information to the values by specifying for Car "blue(blue car)" and for Boat "blue(blue boat)".

Example - implications of changing existing choice list items

When a choice list object is created, only the actual value of the choice list item is stored. This value contains no direct reference to the choice list item from which the value was originally selected. It also does not "know" what the display value was for that selected choice list item.

The value of an object's property is only loosely connected with the choice list via the property definition of the object's class. When determining the display value of the object's property in the UI, the Content Engine tries to match the actual value of the object's property with the current choice list items. It takes the display value of the choice list item that has a matching actual value with the object's property value.

This can become a problem if the choice list has been changed after the object is created. The following scenarios illustrate these potential problems.

Consider a class of Pencil with a property Color, that is associated with a choice list below (listed as Display Value/Stored Value pair):

Red – 1
Green – 2
Blue – 3

The user creates a pencilA object (an object that is an instance of the Pencil class) and selects Red in the drop-down for color. In the CE database, only "1" is stored for pencilA's Color property, not "Red" nor a reference to the choice list item.

Scenario 1: Red is deleted from the choice list

When the user searches for pencils with value of Color as criteria, he will not find it, because it is no longer available as a search value in the drop-down list (you cannot type in a value). Therefore, there is currently no way to find pencilA by searching on Color.

If the user looks at the property of pencilA, it will show a blank value under Color property, with only Green and Blue as the options in the drop-down. In the database, pencilA’s Color still has the value of 1, but since it does not have a matching value in the current choice list items’ actual values (2 and 3), the application will show the default, which is blank. This gives the user a wrong impression that there is currently no value set for the property.

Scenario 2: Red is deleted from the choice list, and a new color, White, is added with Stored Value = 1

The user creates a pencilB and selects White in the drop-down for color. In the database, the only thing stored for the Color property of pencilB is 1, not White. Now the user has pencilA and pencilB both with the same value of 1, while for pencilA it means Red, and for pencilB, it means White. Both pencilA and pencilB will be treated by the application as having the same Color value of 1. When the user searches for White pencils, he I will get both pencilA and pencilB, even though pencilA was meant to be Red when it was created.

When the user looks at the property of pencilA, it will show White display value under Color property, with Green and Blue as the options in the drop-down. But pencilA’s Color should really be Red.

Scenario 3: The stored value of Red is changed to 4

The user creates a new pencilC with Color = Red. In the database, the only thing stored for the Color property of pencilC is 4. Now to the user, pencilA and pencilC should have the same Red color, but to the system, pencilA and pencilC have different colors (1 and 4 respectively). When I try to search for Red pencils, I will get only pencilC when pencilA really should also be a match. When the user looks at the property of pencilC, it will show a blank value under Color property (instead of Red) with Red, Green and Blue as the options in the drop-down.

Conclusion: Using a choice list may not be appropriate if it is expected to change frequently. Note, however, that adding new choice list items to an existing choice list does not run produce the problems in the above scenarios.)