3.5 Conditional Processing

Conditional processing is set with the <condref> reference element, which is usually in a <map> but may appear anywhere in the project, and is effective in its current scope (defined by its enclosing element, typically a <docref> or <map>) until a different <condref> occurs. The <condref> points to a <conditions> definition element, which is usually kept in a library. The <conditions> element has an @id which is used in the <condref> @idref, and contains a set of <cond> elements that specify the conditions to be applied. An empty <conditions> element removes all conditions.

 <conditions id="udoc_experts">
  <cond attr="audience" include="((expert or admin) and not novice)"/>
  <cond attr="product" exclude="(d2g or m2g) and not udoc"/>
 </conditions>

Within the <conditions> set, <cond> can be used with any attribute, and any number of <cond>s can be applied to the same content as long as they each use a different attribute. The process is similar but not identical to that used in DITA.

This checks the content of the @audience; if the attribute is not present, it does nothing. Otherwise, it evaluates the boolean expression, replacing any value present with “true” and any value missing with “false”. If the expression is true, it includes the element and its children:

 <cond attr="audience" include="((expert or admin) and not novice)"/>

Note that if none of the values above are present, as in audience="student", the result will be exclusion; this is equivalent to using the DITA default of exclude.

This also checks the content of the @audience, evaluates the boolean expression, but excludes the element and its children if the expression is true:

 <cond attr="audience" exclude="(novice and not (expert or admin))"/>

In this case, if none of the values are present, the result will be inclusion. Using both include and exclude for the same attribute is unlikely to work as one might want, so a <cond> that has both should be ignored entirely.

If an element has more than one attribute to which <cond>s apply, if any cause exclusion, the result is to exclude, even if others call for inclusion. This is the same rule DITA uses.

<cond> can do flagging as well as include and exclude; @flag specifies a boolean, and @class tells the editor or processor what properties to add to the element content (such as color or underscore, or preceding and following images):

 <cond attr="audience" flag="novice" class="highlight"/>

if you want to flag an element that has a <cond> with @include or @exclude, add a @class to the cond, and the included elements with that attribute will be flagged:

 <cond attr="audience" include="expert or admin" class="confidential"/>

For tables, conditions can be applied to both <row>s and columns. <cell>s that span <row>s or columns are retained if any of their <row>s or columns are retained. <cell>s themselves should not be conditional; make the <cell> contents conditional instead.

The next two subtopics are an example of conditional exclusion and inclusion. They are both the same source file, ud_condtest.mxd:

<doc id="ud_condtest">
<title>Test of Conditions: 
<ph audience="expert">Experts</ph>
<ph audience="novice">Novices</ph>
</title>
<p audience="expert">This para is for experts.</p>
<p audience="novice">This para is for novices.</p>
<p product="d2g">This para is not about uDoc at all.</p>
<relref subjects="conditions" />
</doc>

The first instance uses these conditions:

  <cond attr="audience" exclude="((expert or admin) and not novice)"/>
  <cond attr="product" exclude="(d2g or m2g) and not udoc"/>

and the second instance uses these:

  <cond attr="audience" include="((expert or admin) and not novice)"/>
  <cond attr="product" exclude="(d2g or m2g) and not udoc"/>

Conditions in the rendered output are normally static; hidden elements are simply removed. For some outputs, like HTML (but not Word) rendering can also be dynamic, where the hidden elements are present, but have a @style rule that prevents them from displaying. That allows for user selection of what to hide and show at runtime.

Previous Topic:  3.4 Classes and Formats

Next Topic:  3.5.1 Test of Conditions: Novices

Parent Topic:  Chapter 3. uDoc Processing

Child Topics:

3.5.1 Test of Conditions: Novices

3.5.2 Test of Conditions: Experts

Sibling Topics:

3.1 References and Variables

3.2 Queries

3.3 Related Links

3.4 Classes and Formats

3.6 Branching

3.7 Dynamic Show and Hide

3.8 Output-Dependent Processing