Template Conditional Tag Syntax Documentation

Jeff Mills

Bracket Syntax: ]

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, mostly by Dave Hart:

• Exact match of variable with constant: ]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: ]x:: ... :: ...  ]]
• Boolean "and" of two expressions:

    ]xx::TRUE::FALSE]]]xx::TRUE::FALSE]]::TRUETRUE::
       then-clause
    ::
       else-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 ] tags.

    <convio:then></convio:then>

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

    <conviotherwise></conviotherwise>

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

    Here's an example to further twist your brain.

    
       <convio:choose>
          <convio:when id="whatsontv" title="Affiliate" test="eq">
             <conviop>PR_</conviop>
             <conviop><convio:session title="AffiliateSessionVar" name="80" param="Affiliate"></convio:session></conviop>
             <convio:then>What's On TV?</convio:then>
          </convio:when>
          <convio:when title="events" test="eq">
             <conviop>evt_</conviop>
             <conviop><convio:session title="AffiliateSessionVar" name="80" param="Affiliate"></convio:session></conviop>
             <convio:then>Events</convio:then>
          </convio:when>
          <convio:when title="events" test="eq">
             <conviop>2</conviop>
             <conviop><convio:session title="CurrentApp" name="4"></convio:session></conviop>
             <convio:then>Events</convio:then>
          </convio:when>
          <conviotherwise title="Unknown">Default Affiliate</conviotherwise>
       </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."