Home
This document explains how looped areas of templates are created in Deft templates. We assume a working knowledge of HTML.

The simplest Deft templates have no loops and only colums substituted into the template. Columns are denoted with Perl style variables e.g. $variable. Only scalars are allowed. If a variable does not occur in the data record, it will be left in the template undisturbed (this allows templates to be used as templates).

Looping in Deft is controled by special columns in the data. Deft control columns are created by  the Deft programmer using the special aggregation function dcc(). The memnonic for "dcc" is "declare control column". As far as the templates are concerned, it isn't important how dcc() works, just that such a column will work correctly with the template. There is a special part of the Deft template called the "loop control" which describes what portion of the template is controlled by each control column. Loop controls are surrounded by { } and must have a control column as the first thing inside the { }.

The example below has two control columns: $distinct_t and $distinct_dt (respectively "distinct title" and "distinct title/description").

There are limits to the valid locations of various kinds of data and tags in HTML. In keeping with HTML coding rules, start and stop strings in the control specs are URI encoded. < becomes &lt; and > becomes &gt; This is the type of encoding that your HTML editor will use. If you aren't using an HTML editor you might choose to skip the encoding, although your raw template may not render in a web browser. Deft templates are 100% HTML compliant when encoding is used.

The first control spec is "{$discinct_t start &lt;tr&gt; -2 stop &lt;/tr&gt; +4}". The table below has a breakdown of the parts of the loop control.


1
 2
 3
 4
 5
 6
 7
 8
 9
{
 $distinct_t
 start
 &lt;tr&gt;
 -2
 stop
 &lt;/tr&gt;
 +4
 }

1.
 Left { starts the loop control.
2.
 The column name of the loop control must follow the opening {
3.
 Together 3, 4, and 5 describe the start of the loop. The word "start" is required.
4.
 This string of characters matches part of the template. In the case above, it is URI encoded <tr> or a table row tag. The matches are normal string matches, not regular expressions.
5.
 Count the number match positions. Negative numbers indicate that we move backwards in the template e.g. towards the beginning or left. A - or + sign is required. There are examples below that explain match positions in detail.
6.
 Columns 6, 7, and 8 describe the end of the loop. The word "stop" is required.
7.
 The part of the template to match for the end of the loop. The example above is </tr>.
8.
 The number positions of the stop text match. Plus indicates moving forward (right) in the template. A + or - sign is required.
9.
 The closing } at the end of the loop control.

To reiterate, a control loop is surrounded by { } and it has a controling column, as well as start and stop locations within the template. That's really it.

Below is an example using the second loop control which is highlighted blue box. Incidently, the second loop is "inside" the first loop.

Starting at the second loop control statement "{$distinct_dt start &lt;tr&gt; -2 stop &lt;/tr&gt; +2}" and working backward (left, up) I've labeled four positions around each <tr>. Matches occur on both sides of <tr>. In the example below we are counting backward, so the markers have negative numbers. When you get to a <tr> the first side we encounter is -1, and after we pass <tr> you are at -2. The first side of the next <tr> is -3, and after passing <tr> we are at -4.

The example loop control below goes backwards to -2. I labeled -3 and -4 only to illustrate where these occur.

Going forward from the loop control, we see that the stop matches </tr> and will go to +2. We first encounter </tr> at +1, and after passing </tr> we are at position +2.




Keeping all that in mind, the blue area below highlights the portion of the template controlled by the second loop control. The loop is  one <tr>...</tr> tag, or one row in the table. Everytime this control column ($distinct_dt) has a new distinct value, it will create another row in the table.




Building on what we've done so far, the two loops are highlighted below. The outer loop is green, and the inner loop in blue. Notice that both loops end in the same location. This is fine. Loops can contain other loops. However, loops can't over lap in such a manner that part of a loop is inside and part outside.





Below is a second example as review. For this example, we will use the first loop control hightlighted in the image below.





In the image below the start section is highlighted. The start match is <tr> and is -2. We count backwards to the left side of <tr>.





Using the same example, in the image below, the stop match is </tr> and we count forward +4. That takes us to the location marked in the image on the right side of the lower </tr>. We have passed two </tr> tags, and since we count the first and second positions at each tag, we get to +4 after the second </tr>.