?-Tags: Template Conditional Expression Tags

 

Bracket Syntax:

[[?template_a::template_b::template_c::template_d]]

Mnemonic: "If a contains b, then c, else d"

Each of the four sub-templates has the full expressive power of the template language. The four templates are parsed statically and "compiled" with the parent. At render time, templates a and b are rendered first into two internal buffers. If b is a substring of a, then c is rendered and returned as the value of the entire expression; if not, then d is rendered and returned. In any given case at runtime, exactly three of the four sub templates will be evaluated. The match is an exact character match, i.e. it is case-sensitive and not character set aware. Semantics of the test are those of java.lang.String.indexOf() > 0= - for this reason, an empty string should never be used for b.

Some useful idioms:

  • Exact match of variable with constant: [[?xxconstxx::xx[[A0]]xx:: ... :: ... ]]

    Note how the constant is on the left, and the use of characters it doesn't contain to bracket it and so constrain the substring test to an exact match.

  • Check for null or blank: [[?xxnullx::x[[A0]]x:: ... :: ... ]]

  • Boolean "and" of two expressions:

    [[?[[?xxconst1xx::xx[[A0]]xx::TRUE::FALSE]][[?xxconst2xx::xx[[A5]]xx::TRUE::FALSE]]::TRUETRUE:: then-clause :: else-clause ]]

  • Boolean "or" of two expressions. (A1 equals A2) or (B1 equals B2):

    [[?[[?xA1x::xA2x::TRUE::FALSE]][[?xB1x::xB2x::TRUE::FALSE]]::FALSEFALSE::or-is-false-clause::or-is-true-clause]]

  • There are obvious equivalents for "or" - some less obvious ones:

    • For a simple NOT (a doesn't contain b) just switch the sense around (swap c and d)

    • for an extensible n-way AND, switch the sense and test for a single FALSE

    • for an n-way OR, keep it this way round

    • for 2-way XOR, use [[?TRUEFALSETRUE::(tests)::

    • for 3-way XOR, use [[?TRUEFALSEFALSETRUEFALSE::(tests):: etc. etc.

Syntax

XML Syntax: 

 <convio:choose>
      <convio:when id="unique_ID" {title="description"} {case="true | false"}
              test="empty | nempty | eq | neq | contains | ncontains">
         <convio:op>content to compare 1</convio:op>
         {<convio:op>content to compare 2</convio:op>}
         <convio:then>content to render</convio:then>
      </convio:when>
      {<convio:when id="unique_ID2". . .}
      <convio:otherwise {title="description"}>default content to render</convio:otherwise>
   </convio:choose>

Conditionally renders content. There may be multiple conditions which the TE will regard as mutually exclusive. The first condition that evaluates as "true" will be rendered. If none of the conditions are true then the default <convio:otherwise> content will be rendered.

<convio:choose></convio:choose>

Contains all the conditions and default "otherwise" content.

<convio:when></convio:when>: Contains a condition and the content to render if that condition is successful. Success is selected using the case="" attribute

case="true"

This condition will be successful if it evaluates as true. This is the default behavior if no case="" attribute is present.

case="false"

This condition will be successful if it evaluates as false.

The type of comparison is determined by the value of test="":

test="empty"

This will be true if the value is empty. Requires only one <convio:op></convio:op> element.

test="nempty"

This will be true if the value is not empty. Requires only one <convio:op></convio:op> element.

test="eq"

This will be true if the values match. Requires two <convio:op></convio:op> elements.

test="neq"

This will be true if the values do not match. Requires two <convio:op></convio:op> elements.

test="contains"

This will be true if the second value can be found somewere in the first value. Requires two <convio:op></convio:op> elements.

test="ncontains"

This will be true if the second value cannot be found somewhere in the first value. Requires two <convio:op></convio:op> elements.

 

<convio:op></convio:op>

Contains a value to be compared. This may be text, HTML, or other <convio> / [[Xn]] tags.

<convio:then></convio:then>

Contains text to be rendered. This may be text, HTML, or other <convio> / [[Xn]] tags.

<convio:otherwise></convio:otherwise>

Contains the default text to be rendered if none of the <convio:when> elements are successful. This may be text, HTML, or other <convio> / [[Xn]] tags.

Here's an example:

<convio:choose>
      <convio:when id="whatsontv" title="Affiliate" test="eq">
         <convio:op>PR_</convio:op>
         <convio:op><convio:session title="AffiliateSessionVar" name="80" param="Affiliate"></convio:session></convio:op>
         <convio:then>What's On TV?</convio:then>
      </convio:when>
      <convio:when title="events" test="eq">
         <convio:op>evt_</convio:op>
         <convio:op><convio:session title="AffiliateSessionVar" name="80" param="Affiliate"></convio:session></convio:op>
         <convio:then>Events</convio:then>
      </convio:when>
      <convio:when title="events" test="eq">
         <convio:op>2</convio:op>
         <convio:op><convio:session title="CurrentApp" name="4"></convio:session></convio:op>
         <convio:then>Events</convio:then>
      </convio:when>
      <convio:otherwise title="Unknown">Default Affiliate</convio:otherwise>
   </convio:choose>

First, if the session variable "Affiliate" is "PR_" then we will see the words "What's On TV?" The choose will end and nothing else will be done. If the first condition is not successful we check to see if the session variable "Affiliate" is "evt_" (note that case counts). If that is the case we will see the word "Events." After that, if the current application has an ID of 2 (Calendar) then we will also see the word "Events." Finally, if none of these match we will see the words "Default Affiliate."