A choice list contains a list of predefined choice items that, when associated with a settable property, provide a discrete set of possible values that the property can hold. By associating a property with a choice list, you can enforce restrictions on property values, simplify user entry, and prevent input errors.
Each choice item in a choice list consists of a localizable display name that identifies it and a choice value. If the database used by a given Content Engine installation is case sensitive, the display names of the choice values in its choice lists are also case sensitive. A choice value can hold a single integer or string value that can be assigned to a property, or it can act as a group node and hold a choice list, thus allowing you to organize related choice values into nested groups. There are four types of values that a choice item can represent: a single integer value, a single string value, a group node for a list of integer-type choice items, and a group node for a list of string-type choice items.
There are two types of choice lists: integer and string. Each choice item within a given choice list must have the same data type, either integer or string, which must match the type of the choice list. An integer-type choice list must contain only integer-type choice items and a string-type choice list must contain only string-type choice items. In addition, any choice item within a choice list that acts as a group node must be of the correct choice type (MIDNODE_INTEGER
for integer-type choice lists or MIDNODE_STRING
for string-type choice lists) and must reference a list of choice items of the same choice type. For example, in an integer-type choice list, each choice item must have a ChoiceType property value of INTEGER
(if it represents a single choice value) or MIDNODE_INTEGER
(if it acts as a group node, in which case it must reference a list of choice items with a ChoiceType property value of INTEGER
or MIDNODE_INTEGER
).
To associate a choice list with a property, you can either assign it directly to a property via its property definition or assign it to a property template. Once a choice list have been assigned to a property template, every property derived from that property template is automatically associated with that choice list, thus allowing multiple properties to use a single choice list. A choice list can only be associated with a property definition or property template of the same data type. That is, an integer-type choice list can only be associated with a PropertyDefinitionInteger
or PropertyTemplateInteger
object and a string-type choice list can only be associated with a PropertyDefinitionString
or PropertyTemplateString
object.
A hierarchical choice list is one in which one or more choice items specify a group node that contains a nested list of choices. Each choice item in this nested group can also specify a group node for a nested list of choices, and so on. Hierarchical choice lists allow you to organize choice items according to category. For example, consider a choice list in which each choice item represents a country and each of these choice items contains a nested choice list of choice items representing the cities for that country.
Choice list functionality is provided primarily through three kinds of objects (note that there are two objects named ChoiceList
in two different packages):
com.filenet.api.admin.ChoiceList
: An independently persistable object that represents a single choice list in an object store. Each ChoiceList
object specifies a com.filenet.api.collection.ChoiceList
list collection of Choice
objects. com.filenet.api.collection.ChoiceList
: A simple list collection of Choice
objects. It is returned by the ChoiceValues property of a com.filenet.api.admin.ChoiceList
or Choice
object.Choice
: A dependently persistable object that represents an individual choice item in a choice list. A Choice
object can hold a single possible integer or string value, or it can hold a nested list of choices, in which case the Choice
object defines a com.filenet.api.collection.ChoiceList
list collection of choice items within a choice list. Because it is dependently persistable, the state of a Choice
object is not saved until the independently persistable ChoiceList
object to which it belongs is saved. For code examples demonstrating how to create and use choice list-related objects, see Working with Choice Lists.