Certain map-level attributes cascade throughout a map, which facilitates attribute and metadata management. When attributes cascade, they apply to the elements that are children of the element where the attributes were specified. Cascading applies to a containment hierarchy, as opposed to a element-type hierarchy.
The following attributes cascade when set on the map element or when set within a map:
- audience, platform, product, otherprops, rev
- props and any attribute specialized from props
- linking, toc, print, search
- format, scope, type
- xml:lang, dir, translate
- processing-role
- cascade
- map (most general)
- topicref container (more specific)
- topicref (most specific)
- reltable (more specific)
- relcolspec (more specific)
- relrow (more specific)
- topicref (most specific)
- relrow (more specific)
- relcolspec (more specific)
- topicref container (more specific)
Merging of cascading attributes
The cascade attribute can be used to modify the additive nature of attribute cascading (though it does not turn off cascading altogether). The attribute has two predefined values: "merge" and "nomerge".
- cascade="merge"
- The metadata attributes cascade; the values of the metadata attributes are additive. This is the processing default for the cascade attribute and was the only defined behavior for DITA 1.2 and earlier.
- cascade="nomerge"
- The metadata attributes cascade; however, they are not additive for topicref elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered (that is, setting cascade="nomerge" does not undo merging that took place on ancestors).
Implementers MAY define their own custom, implementation-specific tokens. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens SHOULD consist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the token or method name.
- The predefined values for the cascade attribute MUST precede any implementation-specific tokens, for example, cascade="merge appToken:audience".
- Tokens can apply to a set of attributes, specified as part of the cascade value. In that case, the syntax for specifying those values consists of the implementation-specific token, followed by a parenthetical group that uses the same syntax as groups within the audience, platform, product, and otherprops attributes. For example, a token that applies to only platform and product could be specified as cascade="appname:token(platform product)".
Examples of the cascade attribute in use
Consider the following code examples:
<map audience="a b" cascade="merge"> <topicref href="topic.dita" audience="c"/> </map>
<map audience="a b" cascade="nomerge"> <topicref href="topic.dita" audience="c"/> </map>
For map A, the values for the attribute are merged, and the effective value of the audience attribute for topic.dita is "a b c". For map B, the values for the attribute are not additive, and the effective value of the audience attribute for topic.dita is "c".
In the following example, merging is active at the map level but turned off below:
<map platform="a" product="x" cascade="merge"> <topicref href="one.dita" platform="b" product="y"> <topicref href="two.dita" cascade="nomerge" product="z"/> </topicref> </map>
In map C, the reference to one.dita has effective merged values of "a b" for platform and "x y" for product.
The reference to two.dita turns off merging, so the explicit product value of "z" is used (it does not merge with ancestor values). The platform attribute is not present, so the already-merged value of "a b" continues to cascade and is the effective value of platform on this reference.
Order for processing cascading attributes in a map
When determining the value of an attribute, processors MUST evaluate each attribute on each individual element in a specific order; this order is specified in the following list. Applications MUST continue through the list until a value is established or until the end of the list is reached (at which point no value is established for the attribute). In essence, the list provides instructions on how processors can construct a map where all attribute values are set and all cascading is complete.
For example, in the case of <topicref toc="yes">, applications MUST stop at item 2 in the list; a value is specified for toc in the document instance, so toc values from containing elements will not cascade to that specific topicref element. The toc="yes" setting on that topicref element will cascade to contained elements, provided those elements reach item 5 below when evaluating the toc attribute.
- The conref and keyref attributes are evaluated.
- The explicit values specified in the document instance are evaluated. For example, a topicref element with the toc attribute set to "no" will use that value.
- The default or fixed attribute values are evaluated. For example, the toc attribute on the reltable element has a default value of "no".
- The default values that are supplied by a controlled values file are evaluated.
- The attributes cascade.
- The processing-supplied default values are applied.
- After the attributes are resolved within the map, they cascade to referenced maps.
Note: The processing-supplied default values do not cascade to other maps. For example, most processors will supply a default value of toc="yes" when no toc attribute is specified. However, a processor-supplied default of toc="yes" MUST not override a value of toc="no" that is set on a referenced map. If the toc="yes" value is explicitly specified, is given as a default through a DTD, XSD, RNG, or controlled values file, or cascades from a containing element in the map, it MUST override a toc="no" setting on the referenced map. See Map-to-map cascading behaviors for more details.
- Repeat steps 1 to 4 for each referenced map.
- The attributes cascade within each referenced map.
- The processing-supplied default values are applied within each referenced map.
- Repeat the process for maps referenced within the referenced maps.