The ditavalref element references a DITAVAL document that specifies filter conditions that can be used to process a map or map branch. Other DITAVAL-reference domain elements can be used to imply multiple copies of the map branch that contains them and so apply a different set of conditions to each copy.
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. The branch includes the parent element that contains the ditavalref element, any child elements, and all resources that are referenced by the parent element or its children. While there is no technical restriction that forces ditavalref to appear before peer topic references, placing them first is considered a best practice and all examples in the specification will use this convention.
<map> <topicref href="sampleBranch.dita" audience="admin"> <topicmeta> <navtitle>Navigation title for branch</navtitle> </topicmeta> <ditavalref href="conditions.ditaval"/> <topicref href="insideBranch.dita" platform="win linux mac"/> </topicref> <!-- Other branches not affected by conditions.ditaval --> </map>
- The topicref element that references sampleBranch.dita and all child elements: topicmeta, navtitle, and topicref elements
- The sampleBranch.dita topic
- The insideBranch.dita topic
When more than one ditavalref element is specified in the same branch at the same level, the effective result is one copy of the branch for each ditavalref element. If the example above contains a reference to otherConditions.ditaval as a peer to the existing ditavalref element, the rendered version of this map would reflect two copies of "Sample branch", each reflecting the conditions that are specified in the corresponding DITAVAL document. One copy is created using the conditions in conditions.ditaval, while the other copy uses the conditions from otherConditions.ditaval. Map authors can use specific elements from the DITAVAL reference domain to indicate how resources are renamed, or processors can recover from naming collisions by using an alternate naming scheme. See Limitations below for more information.
<topicref href="ancestor.dita"> <ditavalref href="highLevel.ditaval"/> <topicref href="descendent.dita"> <ditavalref href="lowLevel.ditaval"/> <!-- Other topicrefs --> </topicref> </topicref>
If a ditavalref element is used that does not specify the href attribute, the element is still processed but no additional filtering is applied. This can be used to create an unfiltered copy of a map branch alongside other filtered copies; other aspects of the ditavalref (such as any specified key scope or modified resource name) will still be applied to the branch.
Limitations
The following limitations apply when using the ditavalref element; these limitations cannot be enforced in a DTD or other XML grammar files.
<topicref href="c.dita"> <ditavalref href="one.ditaval"/> <ditavalref href="two.ditaval"/> </topicref>
Processors MAY recover by using an alternate naming scheme for the conflicting copies.
Content models
See appendix for information about this element in OASIS document type shells.
Inheritance
+ map/topicref ditavalref-d/ditavalref
Example
See Examples of branch filtering for several examples of the ditavalref element.
Attributes
The following attributes are available on this element: Universal attribute group (except for conkeyref, which is removed for all elements in this domain) and the attributes defined below.
- href
- Provides 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. See The href attribute for general information on the format and processing implications of the href attribute.
- format
- Format of the target document, which MUST be a DITAVAL document. The default value for this element is "ditaval". See The format attribute for more information.
- processing-role
- The processing role defaults to "resource-only" for DITAVAL documents, which are only used for processing and do not contain content. There is no other valid value for this attribute on this element.