Binding controlled values to an attribute
The controlled values defined in a subject scheme map can be bound to an attribute or an element and attribute pair. This affects the expected behavior for processors and authoring tools.
The <enumerationdef>
element binds the set of controlled values to
an attribute. Valid attribute values are those that are
defined in the set of controlled values; invalid attribute values are those that are
not defined in the set of controlled values. An enumeration can specify an
empty <subjectdef>
element. In that case, no value is valid for
the attribute. An enumeration also can specify an optional default value by using the
<defaultSubject>
element.
If an enumeration is bound, processors SHOULD validate attribute values against the controlled values that are defined in the subject scheme map. For authoring tools, this validation prevents users from entering misspelled or undefined values. Recovery from validation errors is implementation specific.
The default attribute values that are specified in a subject scheme map apply only if a value is not otherwise specified in the DITA source or as a default value by the XML grammar.
To determine the effective value for a DITA attribute, processors check for the following in the order outlined:
- An explicit value in the element instance
- A default value in the XML grammar
- Cascaded value within the document
- Cascaded value from a higher level document to the document
- A default controlled value, as specified in the
<defaultSubject>
element - A value set by processing rules
Example: Binding a list of controlled values to the @audience
attribute
The following example illustrates the use of the <subjectdef>
element to define controlled values for types of users. It also binds the controlled
values to the @audience
attribute:
<subjectScheme>
<!-- Define types of users -->
<subjectdef keys="users">
<subjectdef keys="therapist"/>
<subjectdef keys="oncologist"/>
<subjectdef keys="physicist"/>
<subjectdef keys="radiologist"/>
</subjectdef>
<!-- Bind the "users" subject to the @audience attribute.
This restricts the @audience attribute to the following
values: therapist, oncologist, physicist, radiologist -->
<enumerationdef>
<attributedef name="audience"/>
<subjectdef keyref="users"/>
</enumerationdef>
</subjectScheme>
When the above subject scheme map is used, the only valid
values for the @audience
attribute are "therapist", "oncologist",
"physicist", and "radiologist". Note that "users" is not a valid value for the
@audience
attribute; it merely identifies the parent or
container subject.
Example: Binding an attribute to an empty set
The following code fragment declares that there are no valid values for the
@outputclass
attribute.
<subjectScheme>
<enumerationdef>
<attributedef name="outputclass"/>
<subjectdef/>
</enumerationdef>
</subjectScheme>