Choice lists
You can use a choice list to:
- Prevent users from entering erroneous values.
- Restrict the choices to choices defined by the design of the application.
- Simplify the entry process for the user. When a choice list contains a large number of values, you can group associated values to help users find and choose the needed value.
A choice list is an object that contains a list of choices. An example of a choice list is a list of the two-letter state codes that represent US states. Choices consist of a display value and an actual value that is persisted in the database.
To make a choice list usable, you must assign it to a property template. You cannot 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.
Depending on your database software, you can use choice list items whose only difference is case. For example, one item in a choice list might be set to ITEM1 while another might be set to item1.
To provide users with quick, easy selections when they enter data, follow these guidelines:
- Group choice list elements logically.
- Limit the number of elements in each group.
- Unless you have good reasons to use duplicate values, avoid assigning duplicate values to items in a single choice list. Searches based on choice list values can generate confusing results if the choice lists contain duplicate values. Instead, as explained in the Example: uniqueness of values section, ensure that the values are unique.
- Using a choice list for a property might not be suitable if the values are expected to be changed frequently. While adding new choice list items is safe, changing or deleting the existing choice list items of a current choice list could potentially lead to the kind of unexpected results explained in Example: implications of changing existing choice list items. An example of a choice list whose values do not change is a list of the two-letter state codes that represent US states.
Choice list security
Choice lists have their own security. By default, the Choice List wizard automatically assigns to the new choice list the security that is defined for the Choice List class, which is initially the same security as the object store:
- Object store administrators receive Full Control.
- User groups receive default View Properties access.
To change these default settings, you can either change the default instance security of the Choice List class before creating the choice list, or you can directly edit the security of the choice list by opening its property sheet and directly assigning security. For example, if you have two groups of users with basic View access to the object store, you can deny the right of one of the groups to see a particular choice list.
Example: groups and items
The following
example shows the property sheet of a choice list named Fish
that
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.
Example: uniqueness of values
The
administration console 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. (There are use cases where uniqueness is not desirable.) To
understand the possible consequences of having duplicate item values,
consider the following example:
This example
shows a choice list named "Color choices" that contains the following
duplicate item values: a blue car and a blue boat. After a choice
is made, you cannot tell whether it was the blue car or the blue boat
that was selected. To avoid this uncertainty, you can 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 a property of an object is only loosely connected with the choice list by means of the property definition of the class of the object. When determining the display value of the property of the object in the user interface, Content Platform Engine tries to match the actual value of the 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 property value of the object.
A choice list might not be appropriate if you expect that changes to the list might cause the relationship between stored values and displayed values to change. The following scenarios illustrate the problems that potentially occur when an object references a choice list with a changed item value relationship. Note that only changing or deleting existing items in a choice list (and not adding new items) can cause these potential problems.
Consider a class of Pencil with a property Color, which is associated with the following choice list (listed as Display Value/Stored Value pair):
Green – 2
Blue – 3
The user creates a pencilA object (an object that is an instance of the Pencil class) and selects Red for color. In the pencilA properties, the Color property value is set to 1, 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, pencilA is not found, because it is no longer available as a search value in the 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 Color property of pencilA, the property has a blank value with only Green and Blue as the options in the list. In the database, the Color of pencilA still has the value of 1, but since that value does not match any of the actual item values in the current choice list (2 and 3), the application shows the default, which is blank. The user consequently receives the 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 list 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 are treated by the application as having the same Color value of 1. When the user searches for White pencils, both pencilA and pencilB are returned, even though pencilA was meant to be Red when it was created.
When the user looks at the Color property of pencilA, the property has a value of White with Green and Blue as the options in the list. But the original and intended color of pencilA is Red.
- Scenario 3: The stored value of Red is changed to 4
The user creates a pencilC with Color = Red. In the database, the only thing stored for the Color property of pencilC is 4. The user intends both pencilA and pencilC to have the same Red color, but to the system, pencilA and pencilC have different colors (1 and 4 respectively). When the user tries to search for Red pencils, the system returns only pencilC instead of both pencilC and pencilA. And when the user looks at the Color property of pencilC, the property has a blank value (instead of Red) with Red, Green, and Blue as the options in the list.
This topic is shared by ICS, Filenet 5.5.10. As of: 2023-05-10