Often, we don't want to show all of the wikitext in a template on all tiddlers to which it's applied. Rather, we want to show parts of the wikitext only if some condition is true.

We can achieve this using conditional expressions (or conditionals for short). Conditional expressions are based on filters. If the filter returns at least one result, the contents of the conditional are rendered. Otherwise, nothing at all is rendered. The syntax looks like this:

<% if [<storyTiddler>match[Conditional Expressions]] %>
  The title of the current tiddler is “Conditional Expressions”.
<% endif %>

<% if [<storyTiddler>match[When Pigs Fly]] %>
  Pigs are flying – better watch out!
<% endif %>

The match filter operator passes through any tiddler whose title exactly matches the match step's parameter, and filters out all other tiddlers. It's indispensable in many conditional filters. The <storyTiddler> variable retrieves the name of the tiddler which is currently being shown in the story river. We have to use that in this snippet to get the expected result, rather than <currentTiddler>, because Grok TiddlyWiki snippets are their own tiddlers.

You can see that the filter in the first conditional returns a result, since the title of this tiddler is Conditional Expressions, so the contents of the conditional are rendered. The second returns no results, since the title is not When Pigs Fly, so nothing is rendered.

Notice that a conditional expression looks much like an HTML element, except there are percent signs % right inside the angle brackets, and where you might expect to see <% /if %>, you instead see <% endif %>. The spaces inside the percent signs are optional, but as with the spaces inside {{{ triple braces }}}, your wikitext will quickly become very hard to read if you omit them!

The TiddlyWiki documentation calls this the “conditional shortcut syntax,” which is a big mouthful and hard to remember. In this book, we will call a use of this pattern a conditional expression or occasionally even just a conditional.

A real example

In Templates and the Current Tiddler, we created a ContactInformationTemplate:

!! Information about {{!!title}}

* ''Email'': {{!!email}}
* ''Phone'': {{!!phone}}
* ''Family'': {{!!family}}
* ''Manager'': {{!!manager}}

This template is nice as far as it goes, but it looks rather ugly when applied to a tiddler which is missing some of the fields, such as ChrisSmith:

It would be cleaner to show each bullet point only if the field actually has a value. To achieve this, we can add a conditional expression around each one:

!! Information about {{!!title}}

<ul>
  <% if [all[current]has[email]] %>
    <li>''Email'': {{!!email}}</li>
  <% endif %>
  <% if [all[current]has[phone]] %>
    <li>''Phone'': {{!!phone}}</li>
  <% endif %>
  <% if [all[current]has[family]] %>
    <li>''Family'': {{!!family}}</li>
  <% endif %>
  <% if [all[current]has[manager]] %>
    <li>''Manager'': {{!!manager}}</li>
  <% endif %>
</ul>

The bodies of conditionals can be on one line or multiple lines, and they can contain arbitrary wikitext. Nevertheless, in this example, we needed to switch to using HTML for our list instead of wikitext syntax. The intervening conditionals would split up the bullet points into multiple lists if we used wikitext syntax, preventing them from displaying correctly (see also Block Mode and Inline Mode, in an upcoming chapter).

Nesting and else clauses

What if none of the contact fields are populated? In this case, we might want to provide a message saying that there is no contact information available, so we won't think something is wrong when we look at the template. To achieve this, we'll need to display something both if a condition is true and if it's false. We can do that by adding an <% else %> clause to the conditional, accompanied by an appropriate filter:

<% if [all[current]!has[email]!has[phone]!has[family]!has[manager]] %>

  There is no contact information available for {{!!title}}.

<% else %>

  !! Information about {{!!title}}

  <ul>
    <% if [all[current]has[email]] %>
      <li>''Email'': {{!!email}}</li>
    <% endif %>
    <% if [all[current]has[phone]] %>
      <li>''Phone'': {{!!phone}}</li>
    <% endif %>
    <% if [all[current]has[family]] %>
      <li>''Family'': {{!!family}}</li>
    <% endif %>
    <% if [all[current]has[manager]] %>
      <li>''Manager'': {{!!manager}}</li>
    <% endif %>
  </ul>

<% endif %>

Notice that we've nested the conditionals – put more conditionals inside the <% else %> clause of the outer conditional. As with HTML tags, this is perfectly valid, and even common.

One gotcha to be aware of

In many places in TiddlyWiki, when you want to use a filter, you put it in "quotation marks". No quotation marks are involved in a conditional expression, and if you inadvertently include them, the condition will always be true, no matter what the filter is:

<% if "[<storyTiddler>match[When Pigs Fly]]" %>
  Pigs are flying – perhaps you made a syntax error?
<% endif %>

This can be quite perplexing if you've never seen it before! What's happening is that you're turning the entire filter expression into a single literal tiddler name – namely, a tiddler called [<storyTiddler>match[When Pigs Fly]]. A single tiddler name is a valid filter expression which outputs itself when evaluated, so we get a result, and the contents of the conditional are rendered.

Exercises

<ul>
  <% if [all[current]has[email]] %>
    <li>''Email'': {{!!email}}</li>
  <% endif %>
  <% if [all[current]has[phone]] %>
    <li>''Phone'': {{!!phone}}</li>
  <% endif %>
  <% if [all[current]has[family]] %>
    <li>''Family'': {{!!family}}</li>
  <% endif %>
  <% if [all[current]has[manager]] %>
    <li>''Manager'': {{!!manager}}</li>
  <% endif %>
</ul>

Takeaways