Content inclusion (conref)

The DITA conref attribute provides a mechanism for reuse of content fragments. The conref attribute stores a reference to another element and is processed to replace the referencing element with the referenced element.

The element containing the content reference acts as a placeholder for the referenced element. The identifier for the referenced element must be either absolute or resolvable in the context of the referencing element. (See IDs and references for the details on identifiers.)

More formally, the DITA conref attribute can be considered a transclusion mechanism. In that respect, conref is similar to XInclude as well as HyTime value references. DITA differs from these mechanisms, however, by comparing the constraints of each context to ensure the ongoing validity of the replacement content in its new context. In other words, conref validity does not apply simply to the current content at the time of replacement, but to the ranges of possible content given the constraints of the two document types. A valid conref processor does not allow the resolution of a reuse relationship that could be rendered invalid under the rules of either the reused or reusing content.

If the referenced element is the same type as the referencing element and the list of domains in the referenced topic instance (declared on the domains attribute) is the same as or a subset of the list of domains in the referencing document, the element set allowed in the referenced element is guaranteed to be the same as, or a subset of, the element set allowed in the placeholder element. In the preferred approach, a processor resolving a conref should tolerate specializations of valid elements and generalize elements in the content fragment as needed for the referencing context.

Replacement of the placeholder occurs after parsing of the document but prior to any styling or other transformational or presentational operations on the full topic.

The target of the conref may be substituted based on build-time or runtime conditions. For example, content such as product names or install paths can be separated out from topic content since they change when the topic is reused by other products; the reusing product can substitute their own targets for the conref to allow resolution to their own product name and install paths, and so on.

The target of a conref must be within a DITA topic or DITA map (or point to the entire topic or map). Fragments of DITA content (such as a document containing only a single paragraph) do not contain enough information on their own to allow the conref processor to determine the validity of a reference to them.

The resolved element's attribute specifications can be drawn from both source and target elements in the following priority:

1. All attributes as specified on the source element except for attributes

which specify the value "-dita-use-conref-target"

1. All attributes as specified on the target element except:
   1. The id attribute
   2. Any attribute also specified on the source element such that its specified

value (on the source element) is not "-dita-use-conref-target"

2. The xml:lang attribute has special treatment as described in The xml:lang attribute.

The only time the resolved element would include an attribute whose specified value is "-dita-use-conref-target" is when the target element had that attribute specified with the "-dita-use-conref-target" value and the source element either had no specification for that attribute or had it specified with the "-dita-use-conref-target" value. If the final resolved element (after the complete resolution of any conref chain) has an attribute with the "-dita-use-conref-target" value, that should be treated as equivalent to having that attribute unspecified.

A given attribute value on the resolved element comes in its entirety from either the source or target: the attribute values of the target and source for a given attribute are never additive, even if the property (such as the audience type) takes a list of values.

If the target element has a conref attribute specified, the above rules should be applied recursively with the resolved element from one source/target combination becoming one of the two elements participating in the next source/target combination. The result should preserve without generalization all elements that are valid in the originating context, even if they are not valid in an intermediate context. For example, if topicA and topicC allow highlighting, and topicB does not, then a content reference chain of topicA->topicB->topicC should preserve any highlighting elements in the referenced content. The result is the same as if the conref pairs are resolved recursively starting from the source element.

Parent topic: DITA processing
Previous topic: Navigation behaviors
Next topic: Conditional processing (profiling)