Help:TT Linear Control Structures
HELP PAGE DISCUSSION CLOSE

Controling the flow of the Template Toolkit engine

Control structures allow you to control how TT flows. There are two basic types of control structures, linear and looping control structures. Linear control structures such as IF, ELSIF, ELSE and SWITCH are control structures involved in executing a particular block of code from a list of several blocks depending on different conditions. Looping control structures such as WHILE and FOREACH on the other hand, loop through a block of code continuously while a condition is true. Let's start with an example of the IF control structure.

[% x = 3; IF x == 3; 'Variable x is equal to three.'; END; %]

The example above will result in the output below:

Variable x is equal to three.

We start out by storing the value 3 into the variable x. Then we encounter our first IF control structure block. All control structures must close with an END at the end. All the code in between IF and END is referred to a block. In our case, the line 'Variable x is equal to three.'; is the block. The code above tests to see if the variable x is equal to 3. Since it is, then the block is executed. The line x == 3 is called a conditional statement, which returns a true or a false. As one would expect, if the conditional statement rendered true, the block of the IF will be executed, otherwise skipped over completely. The format for the IF control structure is as follows:

IF condition; ...block of code... END;

The IF control structure can also be extended further more so when the conditional statement following the IF fails, an alternate block of code will be executed.

[% x = 6; IF x == 3; 'Variable x is equal to three.'; ELSE; 'Variable x is not equal to three.'; END; %]

The example above will result in the output below:

Variable x is not equal to three.

The ELSE control structure can be used to catch the situation when the conditional statement under IF turned out to be false. So in our example above, the block 'Variable x is not equal to three.'; was executed because the conditional statement x == 3 was false this time. So basically either the IF block or the ELSE block will always be executed.


IF, ELSIF and ELSE control structures

The IF and ELSE control statements can be extended further with ELSIF to add more conditions to test.

[% x = 3; IF x == 1; 'Variable x is equal to one.'; ELSIF x == 2; 'Variable x is equal to two.'; ELSIF x == 3; 'Variable x is equal to three.'; ELSE; 'Variable x is not one, two or three.'; END; %]

The example above will result in the output below:

Variable x is equal to three.

The code now performs a series of tests until one of the conditions is matched. So variable x is tested to see if it is equal to one, then two, then three. If x did not match another of the conditions, the ELSE block would execute. However, in our example, because x was set to three, the second ELSIF condition of x == 3 is true. This is the final generic format of what the IF, ELSIF and ELSE control structures looks like:

IF condition1; ...block of code when condition1 is true... ELSIF condition2; ...block of code when condition2 is true... ELSE; ...block of code when all conditions are false... END;

The grey text indicates that the code is not required. You can have as many ELSIF control structures between IF and END. Although only the IF and the closing END directives are required, if you were to have ELSIF and/or ELSE clauses, you must put them in the specific order as listed above in the generic format. For instance, you can not start out with a ELSIF, nor can you place ELSE in front of ELSIF.


Available conditional operators

The equal conditional operater == was used in the examples above to see if the left value matched the right, returning either a true or false. Here is a list of additional conditional operators you may use.

symbol  definition                example       results
  ==    equal                     0 == 0        true
  !=    not equal                 1 != 0        true
  <     less than                 2 < 2.5       true
  <=    less than or equal to     -3 <= -5      false
  >     greater than              0.4 > 0.6     false
  >=    greater than or equal to  4 >= 3        true
  !     not                       !true         false
  &&    and                       true && true  true
  ||    or                        true || false true

All conditional statements will ultimately be evaluated as true or false. You can also combine several conditional statements together to define a more specific condition. Here is an example of a more complex condition.

[% x = 3; IF x >= 1 && x <= 7; 'Variable x is between 1 and 7.'; END; %]

The example above will result in the output below:

Variable x is between 1 and 7.

The example above tests to see if the variable x is between 1 and 7. To do so, two conditions are tested in conjunction. In order for the IF block to get executed in the example above, x needs to be greater than or equal to one, and less than or equal to seven. Since our example set x to 3, both the conditions are satisfied. The && operator is the AND operator, so both conditions on the left and right side of the && operator must be true in order for the whole condition to be evaluated to be true. Here are other available operators for combining conditions.

symbol  definition       example          results
  !     not              !true            false
                         !false           true
  &&    and              true && true     true
                         true && false    false
                         false && false   false
  ||    or               true || true     true
                         true || false    true
                         false || false   false

Some times the conditions can get rather long and complicated. Parentheses () can be used to group conditions to specify the order of the condition evaluation. Here is an example how parentheses can change the meaning of the overall conditional statements.

[% x = 5; y = 3; IF (x > 0 && y < 10) || (x <= 3 && y >= 5); "Condition 1 is true.\n"; ELSE; "Condition 1 is false.\n"; END; IF (x > 0 && (y < 10 || x <= 3) && y >= 5); "Condition 2 is true.\n"; ELSE; "Condition 2 is false.\n"; END; %]

The example above will result in the output below:

Condition 1 is true. Condition 2 is false.

In the example above, the variables x and y are initialized to be 5 and 3 respectively. If you look at the two IF statements, you will notice that the two conditional statements look almost identical except for the parentheses. The parentheses determine the order of evaluation. Without parentheses, conditional statements are evaluated from the left to right. So in the first conditional statement (x > 0 && y < 10) || (x <= 3 && y >= 5), the following pieces are evaluated first, (x > 0 && y < 10) and (x <= 3 && y >= 5). The first piece, (x > 0 && y < 10), is true since x being 5 is greater than 0 and y being 3 is less than 10. The second piece, (x <= 3 && y >= 5), is false because x being 5 is not less than or equal to 3. The first conditional statement then becomes (true || false) after the initial evaluation, which is true. So as a result, the string "Condition 1 is true." is printed. Here is a simple break down of the evaluation for the first condition.

step   condition
  1    (x > 0 && y < 10) || (x <= 3 && y >= 5)
  2    (5 > 0 && 3 < 10) || (5 <= 3 && 3 >= 5)
  3    (true && true) || (false && false)
  4    true || false
  5    true

The second conditional statement evaluates differently, as you can see from the result output. The first piece that gets evaluated first is (y < 10 || x <= 3). This is true because y being 3 is less than 10, and while x is not less than or equal to 3, the || operator between the two only needs one of them to be true. Next, x > 0 and y >= 5 are evaluated to be true and false respectively. The second conditional statements now looks like this, (true && true && false). The && operators requires both the left and right conditions to be true to be true overall, and since the condition on the far right was false, the final evaluation is a false. Again, to get a better idea of what is going on, here is a break down of the second evaluation.

step   condition
  1    (x > 0 && (y < 10 || x <= 3) && y >= 5)
  2    (5 > 0 && (3 < 10 || 5 <= 3) && 3 >= 5)
  3    (true && (true || false) && false)
  4    (true && true && false)
  5    false


The SWITCH control structure

Sometimes you will encounter a case where you have a long chain of IF, ELSIF and ELSE statements where you are only matching the value of one variable. This is where the SWITCH control structure comes in. For instance, you might want different strings to be printed depending on what the value of the variable juice holds.

[% juice = 'apple'; IF juice == 'orange'; 'Orange Juice'; ELSIF juice == 'apple'; 'Apple Juice'; ELSIF juice == 'cranberry'; 'Cranberry Juice'; ELSIF juice == 'strawberry'; 'Strawberry Juice'; ELSE; 'Others'; END; %]

The example above will result in the output below:

Apple Juice

Notice that the code above is only testing the content of the variable juice. The code below performs the same exact thing as the code above using the SWITCH control structure.

[% juice = 'apple'; SWITCH juice; CASE 'orange'; 'Orange Juice'; CASE 'apple'; 'Apple Juice'; CASE 'cranberry'; 'Cranberry Juice'; CASE 'strawberry'; 'Strawberry Juice'; CASE; 'Others'; END; %]

You begin by specifying what variable you want to be testing. In our case, we specified juice to be the variable to be tested. You specify all the potential matches you want following the term CASE. If you want a default case (the case that will be matched if none of the specified cases matched), simply do not put a value following the term CASE. So in the code above, the default case is the one where the string 'Others' is being printed. The following is the general layout of the SWITCH control structure.

SWITCH variable; CASE value1; ...block of code when variable == value1... CASE; ...block of code when no cases are matched... END;

The grey text indicates that the code is not required. You can also have as many cases as you want matched. Click Here for more information on linear control structures.


Back to Table of Contents