The if:choose Element

The if:choose element, together with the if:when and if:else elements, provides branching and fallback capabilities for conditional processing. Use the if:choose element if you need to select only one from a number of conditions, or if you need to provide fallback content only when conditions are not met.

The if:choose and if:when elements also allow you to hide conditional content from processing tools that don't support conditional processing. See Fallback Behavior for details.

Notes

  • The if:choose element contains one or more if:when elements, optionally followed by general block content or an if:else element.

  • The if:choose element can occur in any general block context.

  • At most one child if:when element is displayed, or the fallback block content or if:else element is displayed.

  • The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.

  • The if:choose element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Output only one of a group of conditionals:

<if:choose>
  <if:when test="target:xhtml">
    <p>This is only output to XHTML.</p>
  </if:when>
  <if:when test="target:html">
    <p>This is only output to HTML.</p>
  </if:when>
  <if:when test="target:pdf">
    <p>This is only output to PDF.</p>
  </if:when>
</if:choose>

Output one thing when showing content for Android-based systems, and something else otherwise:

<if:choose>
  <if:when test="platform:android">
    <p>This is output for Android.</p>
  </if:when>
  <if:else>
    <p>This is output otherwise.</p>
  </if:else>
</if:choose>

Do the exact same as above, but with differnt fallback behavior when processed with tools that do not support conditionals.

<if:choose>
  <if:when test="platform:android">
    <p>This is output for Android.</p>
  </if:when>
  <p>This is output otherwise.</p>
</if:choose>

This is output otherwise.

See Examples on the page The test and if:test Attributes for examples of more complicated test expressions.

Processing Expectations

The if:choose element is a branching element. At most one of its child if:when elements is displayed, or else fallback content is displayed. A processing tool evaluates each child if:when in turn, evaluating its test attribute. Once an if:when element is found whose test attribute evaluates to true, its contents are processed in block mode, and further processing of the if:choose element stops.

If no child if:when element is displayed, the fallback content is displayed. The fallback content is any block content that is a direct child of the if:choose element, plus any block content contained in a child if:else element, all processed in document order. Both are allowed, because they have different fallback behavior in tools that don't support conditional processing. See Fallback Behavior for details.

Schema

The formal definition of the Mallard Conditionals extension is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the if:choose element. The namespace declarations for this definition are on the page Conditionals 1.0.

if_choose = element if:choose {
  if_choose_attr,
  if_when +,
  ( if_else |
    mal_block * ) ?
}
if_choose_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_block_elements |= if_choose
© 2011, 2012 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard