{break}

Leaves a loop at once: the rest of the current pass is dropped and no further row follows.

Loops and trees Single tags

Syntax 

{break}
{break 'name'}

Parameters

level
Optional: which loop. The name of an enclosing tag or its name= ('items'), a level number, or a negative offset counting levels up from here. Without it, the nearest enclosing loop - past an {if}, a {case} and any other level that renders once for the row it stands in.

Description

{break} stops a loop dead, like PHP's break: what is left of the current pass after the tag is dropped, and no further row follows. It is usually written inside an {if} - stop at the first row that matches. The tag prints nothing.

It works on rows and on conditions alike: in a data tag or a {sequence} the rows still to come are emptied, and in a {while} or {until} the loop asks for no further pass. For a stop that lets the current pass finish, use {cease}; to skip one pass only, {continue}.

Without a parameter it leaves the nearest enclosing loop, past an {if}, a {case} and any other level that renders once for the row it stands in - an {ifchanged}, a {guest}, a property pair, a snippet. A name - {break 'orders'}, a tag's name or its name= - leaves an outer loop, and the inner loops with it; a level number or a negative offset picks the level by position. Under the strict syntax check a name no enclosing level has is an error.

Examples

Stop at the first match

The loop stops at the first score above 90; the rest of that pass and the rows after it are dropped.

Templateexamples/break/1-first.pad 
<ul>
{scores}
  {if $points gt 90}<li>{$player} scored {$points} - found one, stop.</li>{break}{/if}
  <li>{$player}: {$points}</li>
{/scores}
</ul>
PHPexamples/break/1-first.php 
<?php

  $scores = [
    [ 'player' => 'Ann',  'points' => 71 ],
    [ 'player' => 'Ben',  'points' => 84 ],
    [ 'player' => 'Cleo', 'points' => 96 ],
    [ 'player' => 'Dirk', 'points' => 99 ],
    [ 'player' => 'Ed',   'points' => 60 ] ];

?>
Resultopen alone
  • Ann: 71
  • Ben: 84
  • Cleo scored 96 - found one, stop.

Breaking out of two loops

Named, break leaves the outer loop too - the search ends at the first hit.

Templateexamples/break/2-outer.pad 
{set $target = 12}
<p>
{sequence '1..6', name='x'}
  {sequence '1..6', name='y'}
    {if $x * $y eq $target}First pair: {$x} &times; {$y} = {$target}{break 'x'}{/if}
  {/sequence}
{/sequence}
</p>
Resultopen alone

First pair: 2 × 6 = 12

Breaking a while

A loop with a generous condition, left as soon as the sum passes 20.

Templateexamples/break/3-while.pad 
{set $sum = 0}
{set $add = 0}
<p>
{while $add lt 100}
  {increment $add}
  {set $sum = $sum + $add}
  {if $sum gt 20}{break}{/if}
  {$sum}
{/while}
</p>
<p>Stopped when adding {$add} made {$sum}.</p>
Resultopen alone

1 3 6 10 15

Stopped when adding 6 made 21.

See also

  • {cease} Ends a loop gracefully: the current pass finishes, and no further row follows.
  • {continue} Skips the rest of the current pass of a loop and goes on with its next row.
  • {while} Renders its content again and again for as long as a condition holds.
  • {sequence} Generates a range, a list or one of 80 mathematical sequences, and iterates its values.