The test and if:test Attributes

The test attribute contains a test expression that determines whether or not an element or group of elements is shown. On the dedicated conditional elements if:if and if:when, use the test attribute with no namespace. Otherwise, use the namespaced if:test attribute.

Notes

The test attribute without a namespace occurs on the if:if and if:when elements.
The namespaced if:test attribute can occur on any block element or list item.
The test and if:test attributes both take a test expression as content.
A test expression is made up of one or more test clauses, separated by commas, and is true if any clause is true.
A test clause is made up of one or more test tokens, separated by spaces, and is true if all tokens are true.
Prefix any token with an exclamation point to negate it.

Examples

The following examples show the if:test element used on standard Mallard block elements. The same test expressions can be used with the test attribute on the if:if and if:when elements. See those pages for more examples.

Only output a paragraph when viewing on a mobile device:

<p if:test="target:mobile">This is only output for mobile.</p>

You can negate a token by prefixing it with an exclamation point. Output a paragraph only when not viewing on a mobile device:

<p if:test="!target:mobile">This is not output for mobile.</p>

You can join multiple tokens with spaces to test that they are all true. Only output a paragraph when the content is for running under GNOME 3 on a Linux-based system:

<p if:test="platform:gnome-shell platform:linux">This is for GNOME 3 on Linux.</p>

You can join multiple clauses with commas to test that any clause is true. Output a paragraph when the content is for either GNOME 3 or GNOME 2:

<p if:test="platform:gnome-shell, platform:gnome-panel">This is for GNOME 2 or 3.</p>

You can combine the matches for all tokens and any clause. There is no grouping, so you must normalize the expression into an appropriate form. Output a paragraph when the content is for either GNOME 3 or GNOME 2, and it is only for Linux-based systems:

<p if:test="
  platform:gnome-shell platform:linux, platform:gnome-panel platform:linux
">This is for GNOME on Linux.</p>

You can mix negations into expressions. Negations always apply to tokens, not to clauses or entire expressions. Output a paragraph when the content is for either GNOME 3 or GNOME 2, but only for non-Linux-based systems:

<p if:test="
  platform:gnome-shell !platform:linux, platform:gnome-panel !platform:linux
">This is for GNOME, but not on Linux.</p>

You can also use the if:test attribute on list items for basic lists, step lists, term lists, and tree lists:

<steps>
  <item if:test="platform:gnome-shell"><p>Click <gui>Activities</gui>.</p></item>
  <item if:test="platform:gnome-panel"><p>Click <gui>Applications</gui>.</p></item>
  <item><p>Under <gui>Games</gui>, open <gui>Five or More</gui>.</p></item>
</steps>

Processing Expectations

When the if:test attribute occurs on a block element or list item, that element is only shown if the test expression evaluates to true, as defined below. Otherwise, the element is ignored, as if it were not in the document.

When the test attribute occurs on an if:if or if:when element, the test expression is evaluated to true or false as defined below, then the processing rules for those elements are followed.

Processing tools evaluate test expressions according to the following rules:

Split test expressions into test clauses on comma characters (U+002C). Evaluate each test clause, ignoring empty or whitespace-only clauses. An expression is true if any clause is true.
Split each test clause into test tokens on space characters (U+002A). Evaluate each test token, ignoring empty tokens. A clause is true if all of the tokens are true.
If a test token starts with an exclamation point (U+0021), remove the leading exclamation and evaluate the remaining token, then negate that truth value.
In most applications, a token evaluates to true only when it is explicitly defined. Processing tools have a list of defined tokens. These tokens may come from any combination of built-in lists, lists generated based on computed values, and user-defined tokens. Some tokens may require special handling. See Test Tokens for details.

By default, tokens are false unless defined true. Some special-purpose processing tools, however, may behave differently. A pre-processing filter tool, for example, may have a list of false tokens and rewrite expressions accordingly. Some processing tools may assign maybe values to some tokens to defer certain conditionals to a target format.

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 test and if:test attributes. The namespace declarations for this definition are on the page Conditionals 1.0.

if_attr_test = attribute test { text }
if_attr_if_test = attribute if:test { text }
mal_block_attr &= if_attr_if_test ?
mal_block_list_item_attr &= if_attr_if_test ?
mal_block_steps_item_attr &= if_attr_if_test ?
mal_block_terms_item_attr &= if_attr_if_test ?
mal_block_tree_item_attr &= if_attr_if_test ?