4.11. Flow Control

Flow control is about making unexpected changes to the execution order of a template. This can be as simple as ending a FOREACH loop early, or as significant as ending the entire template processing process. These are generally exceptional cases, so you probably won't need to use flow-control directives that often, but we discuss them here just in case.

4.11.1. RETURN

The RETURN directive can be used to stop processing the current template and return to the template from which it was called, resuming processing at the point immediately after the INCLUDE, PROCESS, or WRAPPER directive. If there is no enclosing template, the Template process( ) method will return to the calling code with a true value.

Before
[% INCLUDE half_wit %]
After

[% BLOCK half_wit %]
This is just half...
[% RETURN %]
...a complete block
[% END %]

The previous example produces the following output:

Before
This is just half...
After

4.11.2. STOP

The STOP directive can be used to indicate that the processor should stop gracefully without processing any more of the template document. This is a planned stop, and the Template process( ) method will return a true value to the caller. This indicates that the template was processed successfully according to the directives within it.

[% IF something.terrible.happened %]
   [% INCLUDE fatal/error.html %]
   [% STOP %]
[% END %]

[% TRY %]
   [% USE DBI(mydsn) %]
   ...
[% CATCH DBI.connect %]
   <p>Cannot connect to the database: [% error.info %]</p>
   <br>
   We apologize for the inconvenience.  The cleaning lady 
   has removed the server power to plug in her vacuum cleaner.
   Please try again later.
   </p>
   [% INCLUDE footer %]
   [% STOP %]
[% END %]

4.11.3. NEXT

The NEXT directive can be used to start the next iteration of a FOREACH or WHILE loop:

[% FOREACH user = userlist %]
   [% NEXT IF user.isguest %]
   Name: [% user.name %]    Email: [% user.email %]
[% END %]

4.11.4. LAST

The LAST directive can be used to prematurely exit a FOREACH or WHILE loop:

[% FOREACH user = userlist %]
   Name: [% user.name %]    Email: [% user.email %]
   [% LAST IF some.condition %]
[% END %]

BREAK can also be used as an alias for LAST.