<ditavalref>

Processing expectations

When a <ditavalref> element is included in a map, the conditions in the referenced DITAVAL document are used to filter the elements in the branch. See Branch filtering for details on how to process maps with this element.

It is possible to construct a root map where use of this element results in resource name conflicts. See Handling resource name conflicts caused by branch filtering for details on how to recover from name conflicts.

Specialization hierarchy

The <ditavalref> element is specialized from <topicref>. It is defined in the DITAVAL-reference domain module.

Attributes

The following attributes are available on this element: universal attributes (except for @conkeyref, which is removed for all elements in this domain), @format, @href, @impose-role, @processing-role, and @scope.

The following attributes are available on this element: universal attributes (except for @conkeyref which is removed for all elements in this domain) and the attributes defined below.

@format (link-relationship attributes)

Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.

The @format attribute has a default value of ditaval.

@href (link-relationship attributes)

Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.

The @href attribute specifies a reference to a DITAVAL document. If the @href attribute is unspecified, this <ditavalref> will not result in any new filtering behavior, but other aspects of the element are still evaluated.

@impose-role

Specifies whether this element will impose its role on elements in a referenced map. The attribute is ignored if the target of the reference is not a map or branch of a map. The following values are valid:

keeptarget

The role of the current reference is not imposed on the target of the reference. This is the default for the unspecialized <topicref> element and for many convenience elements such as <keydef>.

impose

The role of the current reference is imposed on the target of the reference. For example, if a specialized topic reference <chapter> uses this value and references a map, a topic reference that resolves in place of the <chapter> will be treated as if it were a chapter.

-dita-use-conref-target

See Using the -dita-use-conref-target value for more information.

See Imposing roles when referencing a map for detailed information on processing implications.

The @impose-role attribute has a fixed value of keeptarget.

@processing-role (common map attributes)

Specifies whether the referenced resource is processed normally or treated as a resource that is only included in order to resolve references, such as key or content references. The following values are valid:

normal

Indicates that the resource is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.

resource-only

Indicates that the resource should be used only for processing purposes. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

-dita-use-conref-target

See Using the -dita-use-conref-target value for more information.

If no value is specified but the attribute is specified on a containing element within a map or within the related-links section, the value cascades from the closest containing element.

The @processing-role attribute has a default value of resource-only.

@scope (link-relationship attributes)

Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See The scope attribute for detailed information on supported values and processing implications.