2.1.3.5 Content inclusion (conref)

• The @conref or @conkeyref attribute can be used to pull the referenced content into the location of the referencing element. The combination of either of these attributes with the @conrefend attribute can be used to pull the content of a range of elements.

• The @conref attribute can be used in combination with the @conaction attribute to push content from the referencing element to the location of the referenced element.

Pulling content to the referencing element

When the @conref or @conkeyref attribute is used alone, the referencing element acts as a placeholder for the referenced element, and the content of the referenced element is rendered in place of the referencing element.

The combination of the @conrefend attribute with either @conref or @conkeyref specifies a range of sibling elements that is rendered in place of the referencing element. See The conrefend attribute for examples of how to combine @conrefend with either @conref or @conkeyref.

Pushing content from the referencing element

The @conaction attribute reverses the direction of reuse from pull to push. When the @conref or @conkeyref attribute is used in combination with the @conaction attribute, content can be rendered before, after, or in place of the referenced element, depending on the value of the @conaction attribute. See The conaction attribute for more details.

Note: The @conaction and @conrefend attributes cannot both be used within the same referencing element, so it is not possible to push a range of elements.

The identifier for the referenced element must be either absolute or resolvable in the context of the referencing element.

More formally, the DITA @conref attribute can be considered a transclusion mechanism similar to XInclude and to HyTime value references. DITA differs from these mechanisms, however, in that 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 both the referencing document type and the referenced document type. DITA compares the constraints of each context to ensure the continued validity of the replacement content in its new context. A conref processor must not permit resolution of a reuse relationship that could be rendered invalid under the rules of either the reused or reusing content.

When pulling content with the conref mechanism – if the referenced element is the same type as the referencing element, and the list of domains declared on the domains attribute in the referenced topic or map instance is the same as or a subset of the list of domains declared 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 referencing element. A processor resolving a conref should tolerate specializations of valid elements and should generalize elements in the pulled content fragment as needed for the referencing context.

When pushing content with the conref mechanism, the domain checking algorithm is reversed. In this case, the domains attribute on the referenced document's topic or map must be the same as or a superset of the domains declared on the referencing document. Once again, a processor resolving a conref should tolerate specializations of valid elements and should generalize elements in the pushed content fragment as needed for the referenced context.

All replacement of content based on @conref occurs after parsing of the document but prior to any styling or other transformational or presentational operations on the full topic.

The referenced element may replace the referencing element based on build-time or runtime conditions. For example, content such as product names or install paths may differ from one product to another. It is advantageous to separate such content from topic content which is reused for more than one product. When the content is reused in a different context, different resources are substituted as reference elements.

A fragment of DITA content, such as an XML document containing only a single paragraph without a topic or map ancestor, does not contain enough information for the conref processor to be able to determine the validity of a reference to it. Consequently, the value of a conref must specify a referenced element within a DITA topic or DITA map (or it may point to the entire topic or map).

The only time the resolved element would include an attribute whose specified value is "-dita-use-conref-target" is when the referenced element had that attribute specified with the "-dita-use-conref-target" value and the referencing element either had no specification for that attribute or had it also specified with the "-dita-use-conref-target" value. If the final resolved element (after the complete resolution of any conref chain, as explained below) 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 referencing element or the referenced element; the attribute values of the referencing and referenced elements for a given attribute are never additive, even if the property (such as the audience type) takes a list of values.

If the referenced element has a @conref attribute specified, the above rules should be applied recursively with the resolved element from one referencing/referenced combination becoming one of the two elements participating in the next referencing/referenced 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, however it is achieved, must be equivalent to the result of resolving the conref pairs recursively starting from the original referencing element in topicA.

The @conrefend attribute is used when referencing a range of elements with the conref mechanism. The @conref attribute references the first element in the range, while @conrefend points to the last element in the range. Although the start and end referenced elements must both be of the same type as the referencing element (or specialized from that element type), the intermediary, contiguous nodes in the middle of the range do not have to be the same.