Choice Lists

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 Content Platform 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. A choice item can represent four types of values: 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 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 with its property definition or assign it to a property template. After a choice list is assigned to a property template, every property that is 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 be associated only with a property definition or property template of the same data type. That is, an integer-type choice list can be associated only with a PropertyDefinitionInteger or PropertyTemplateInteger object and a string-type choice list can be associated only 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 that represent the cities for that country.

Choice List Objects

Choice list function is provided primarily through three kinds of objects (note that two objects are 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 that demonstrate how to create and use choice list-related objects, see Working with Choice Lists.