<prop>

The <prop> element in a DITAVAL document specifies filtering or flagging actions that occur when rendering. The actions target the @props attribute or specializations of @props, including @audience, @deliveryTarget, @otherprops, @platform, and @product.

Usage information

The following table lists the functions that are performed by the <prop> element in a DITAVAL document:

Markup Result
A <prop> element that specifies both an @att and a @val attribute Specifies an action (exclude, flag, include, or pass through) for the attribute or attribute group with the specified value
A <prop> element that specifies only an @att attribute Sets a default action for the specified attribute or attribute group
A <prop> element without an @att and @val attribute Sets a default action for all conditional-processing attributes not explicitly specified in the DITAVAL document

Rendering expectations

For the @color and @backcolor attributes on <prop> and <revprop>, processors SHOULD support at least the following values:
For the @style attribute on <rev> and <revprop>, processors SHOULD support the following tokens:
  • bold
  • double-underline
  • italics
  • overline
  • underline

In addition, processors MAY support proprietary tokens for the @style attribute. Such tokens SHOULD have a processor-specific prefix to identify them as proprietary. If a processor encounters an unsupported style token, it MAY issue a warning, and it MAY render content that is flagged with such a style token by using some default formatting.

Processing expectations

The following markup in a DITAVAL document is an error condition:
  • More than one <prop> element with no @att attribute
  • More than one <prop> element with the same @att attribute and no value
  • More than one <prop> element with the same @att attribute and same @value
Processors MAY provide an error or warning message for these error conditions.

The following list outlines how processors apply @outputclass flags:

  • If one or more DITAVAL properties apply @outputclass flags to the same element, and the element already specifies one or more values for the @outputclass attribute, processors treat the element as if the tokens for the @outputclass attribute that were provided in the DITAVAL document are specified first.
  • If two or more DITAVAL properties apply @outputclass flags to the same element, processors treat the element as if each value was specified for the @outputclass attribute. The order of the tokens for the @outputclass attribute that were provided in the DITAVAL document is undefined.

Content model

<startflag>?, <endflag>?

Contained by

<val>

In order
  1. Optional <startflag>
  2. Optional <endflag>

Contained by

  • <val>

Attributes

The following attributes are available on this element:

@action (REQUIRED)

Specifies the action to be taken. The following values are supported:

exclude
Indicates that the content is excluded from the output, if all values for the specified attribute are excluded.
flag
Indicates that the content is included in the output and flagged, if the content has not been excluded.
include
Indicates that the content is included in the output. This is the default behavior, unless otherwise set.
passthrough
Indicates that the content is included in the output and that the attribute value is preserved. This enables further processing by a runtime engine.
@att
Specifies the conditional-processing attribute that is targeted. The value is the literal attribute name or the name of a group within one of those attributes, with the group name specified using the generalized attribute syntax. If the @att attribute is absent, then the <prop> element declares a default behavior for anything not explicitly specified in the DITAVAL document.
@val
Specifies the attribute value that is targeted. If the @val attribute is absent, then the <prop> element declares a default behavior for any value in the specified attribute.

The following attributes are only applicable when the @action attribute is set to flag. If the @action attribute is not set to flag, any value specified for these attributes are ignored.

@backcolor
Specifies the background color for flagged text. Colors can be entered by name or hex code. When images are flagged, the background color is rendered as a thick border.
@color
Specifies the color for flagged text. Colors can be entered by name or hex code. When images are flagged, the color is rendered as a thin border.
@outputclass
Specifies a value for the @outputclass attribute. The flagged element is treated as if the specified @outputclass value was specified on that element.
@style
Specifies the formatting to use for flagged text. This attribute can contain multiple space-delimited tokens.
@action (REQUIRED)

Specifies the action to be taken. The following values are supported:

exclude
Indicates that the content is excluded from the output, if all values for the specified attribute are excluded.
flag
Indicates that the content is included in the output and flagged, if the content has not been excluded.
include
Indicates that the content is included in the output. This is the default behavior, unless otherwise set.
passthrough
Indicates that the content is included in the output and that the attribute value is preserved. This enables further processing by a runtime engine.
@att
Specifies the conditional-processing attribute that is targeted. The value is the literal attribute name or the name of a group within one of those attributes, with the group name specified using the generalized attribute syntax. If the @att attribute is absent, then the <prop> element declares a default behavior for anything not explicitly specified in the DITAVAL document.
@backcolor
Specifies the background color for flagged text. Colors can be entered by name or hex code. When images are flagged, the background color is rendered as a thick border.
@color
Specifies the color for flagged text. Colors can be entered by name or hex code. When images are flagged, the color is rendered as a thin border.
@outputclass
Specifies a value for the @outputclass attribute. The flagged element is treated as if the specified @outputclass value was specified on that element.
@style
Specifies the formatting to use for flagged text. This attribute can contain multiple space-delimited tokens.
@val
Specifies the attribute value that is targeted. If the @val attribute is absent, then the <prop> element declares a default behavior for any value in the specified attribute.

Example

This section is non-normative.

The following code sample shows a DITAVAL document that contains three <prop> elements:

<?xml version="1.0" encoding="UTF-8"?>
<val>
  <prop action="exclude"/>
  <prop action="passthrough" att="otherprops"/>
  <prop action="include" att="product" val="base-product"/>
</val>

The following list outlines the actions that the DITAVAL document specifies:

  1. Sets a default action of exclude. With the exception of the other conditions that are specified in the above DITAVAL document, the content of any element that specifies a conditional-processing attribute is excluded from the rendered output.
  2. Sets a default action of passthrough for the @otherprops attribute. The content of any element that specifies the @otherprops attribute is included in the output. In addition, the value for the @otherprops attribute is preserved in the rendered output, if supported by the output format.
  3. Sets an action of include for any element that specifies a value of base-product for the @product attribute. The content of any element that specifies a value of base-product for the @product attribute is included in the rendered output.

When a DITA map is processed using the above DITAVAL document, the following DITA elements are excluded:

  1. Any element for which the @audience, @deliveryTarget, @platform, and @props attributes (or specializations of @props) specify a non-null value.
  2. Any element for which the @product attribute specifies a value that is not equal to base-product.

All other content is included.