Homespacer>spacerMergemill Tags Guidespacer>spacerLooping Tags

spacer

Content Field

Expression

Looping

Branching

System Values

Statistics

Sections

Example

spacer

<?Loop: Count?>
<?Exit?>
<?EndLoop?>

Loop tags are used to designate a part of the template to be repeated in generating the output. Mergemill manages each loop separately when running the template, and treats all out-loop template segments together as one special loop body.

Each job has one associated template. The template is automatically run as many times as necessary to exhaust all primary feeds. The actual number of times the template is run depends on the use of loops. For a template without loop, the feeds for the out-loop fields are considered primary, and must be all used as instructed by the template. If a template contains loops, only the feeds for the in-loop fields are regarded as primary. Feeds for the out-loop fields play a supporting role, and do not need to be exhausted.

space
Template Without Loop

A template without loop is often used to generate detail web pages, which usually show the full information of each entity on a separate page. Mergemill runs the template repeatedly to exhaust all feeds.

The entire template in this case is one special loop body, which is different in two ways from a common loop. First, the template is run once for each generated page. Second, if you have selected the "Outloop fields data loop back" option in the job definition, fields that run out of data before others in their current stream will loop back to the beginning of their current stream on the next run of the template. Likewise, fields that run out of data streams before others will loop back to their first stream on the next run. If the "Outloop fields data loop back" option is not selected, empty values will be inserted when available data for a field is exhausted.

Consider the following HTML code segment:

<p>Sales in Year <?[Year]{4}?></p>
<table width="700" border="1" cellspacing="0" cellpadding="3">
<tr>
<td width="200" bgcolor="#<?[BgColor1]?>"><p>Q1 Sales</p></td>
<td width="500" bgcolor="#<?[BgColor1]?>"><p><?[Sales]{1}@##,###,##0?></p></td>
</tr>
<tr>
<td width="200" bgcolor="#<?[BgColor2]?>"><p>Q2 Sales</p></td>
<td width="500" bgcolor="#<?[BgColor2]?>"><p><?[Sales]{2}@##,###,##0?></p></td>
</tr>
<tr>
<td width="200" bgcolor="#<?[BgColor1]?>"><p>Q3 Sales</p></td>
<td width="500" bgcolor="#<?[BgColor1]?>"><p><?[Sales]{3}@##,###,##0?></p></td>
</tr>
<tr>
<td width="200" bgcolor="#<?[BgColor2]?>"><p>Q4 Sales</p></td>
<td width="500" bgcolor="#<?[BgColor2]?>"><p><?[Sales]{4}@##,###,##0?></p></td>
</tr>
</table>

The single-stream feed for Year and Sales is from a CSV text file with contents partly shown below.

space"Year","Quarter","Sales"
space2000,1,1186100
space2000,2,945300
space2000,3,1077200
space2000,4,1683300
space2001,1,1308200
space...

The single-stream feed for BgColor1 and BgColor2 is from another file containing the following one line:
space"eeeeff","ffeeee"

When the job is run, a web page is generated for each year listing the four quarterly sales figures. The column number 4 in the Year tag causes Mergemill to skip three values in each run of the template, to keep the Year and Sales figures in step. The multiple occurrences of BgColor1 and BgColor2 use the same data values, i.e. eeeeff and ffeeee respectively.

Assuming the "Outloop fields data loop back" option is selected, on the second run of the template, Year and Sales continue on with their data stream, and BgColor1 and BgColor2 start from the beginning again because their stream was used up in the first run.

space
Template With Loops

Loops are often used in a template to generate index web pages. Such pages are for easy navigation to the detail pages produced using a template without loop, usually from the same feeds.

At the start of the job, the template is run several times to produce a set of pages to exhaust the first data streams for the in-loop fields. This is then repeated for the next set of data streams and so on, till all streams for the in-loop fields are used. If you do not set any break condition for any loop, stream break is then the only loop break, and one index page is produced for each set of data streams.

In a template with loops, in-loop fields are primary. The job ends when data feeds for all in-loop fields are used, even if there are unused streams for out-loop fields. Furthermore, out-loop fields move through their data streams in step with in-loop fields. So when a page set is done, all fields move onto their next data stream. Unused data in the current streams for out-loop fields are ignored.

space
Loop Breaks

All loops automatically break at stream breaks. You may set conditions to also break a loop before the end of streams. The easiest way is to use the Count attribute in the Loop tag. The loop will repeat the specified number of times on each run of the template to generate a page.

Another way to break a loop before the end of streams is to leave out the Count attribute, use an IF structure in the loop body to test for the break condition, and put the Exit tag in the appropriate part of the IF construct. For example you may have something like this in your template:

space<?Loop?> ... <?If(Same[BrkField]{2})?><?Else?><?Exit?><?EndIf?><?EndLoop?>

The order of loop-break control is therefore this: the Exit tag, the loop Count attribute, and finally data feed stream breaks.

space
Loops in Action

Suppose we have a template with two loops. Loop 1 is set to break on counts of 20. Loop 2 does not have any break condition set. There are 3 streams in the feeds for the out-loops fields, 2 in the feeds for loop 1 fields, and 4 in the feeds for loop 2 fields. Each column in the first stream for loop 1 fields contains 58 data values, and in the second stream 63.

space
:: First Page-Set

On the first run of the template, Mergemill fetches the first set of data values from the first streams for the out-loop fields. When it comes to loop 1, it repeats the loop body 20 times till the first 20 data values for loop 1 fields are used. Then it leaves the loop and continues on. When it comes to loop 2, it repeats the loop body till all the data values in the first stream for each in-loop field are exhausted. Fields with shorter streams will get empty values till the longest stream is done. Mergemill then continues on to the end of the template. This produces the first page from the first data streams.

Since the first streams for the fields in loop 1 are not yet exhausted, the template is run again. If there is sufficient data, the out-loop fields use the second set of data values in the first streams. When Mergemill comes to loop 1, it repeats the loop body till the second 20 data values for the in-loop fields are used. Then it continues on to loop 2, which is skipped entirely since there is no more unused data in the current streams. Mergemill continues on to the end of the template to complete the second page in the first page set.

The template is run the third time to finish up the last 18 data values for the fields in loop 1. Mergemill then continues on to the end of the template, skipping loop 2 again. This completes the first set of 3 pages.

space
:: Second Page-Set

Next, the template is run 4 times to produce the second set of 4 pages to exhaust the second data stream for each in-loop field in loop 1. Like before, loop 2 will use up the second data streams on the first page of this page-set. If there are sufficient data, the out-loop fields use 4 sets of data values in the second streams for the 4 pages. Out-loop fields having insufficient data are handled according to the job's "Outloop fields data loop back" option setting.

space
:: Subsequent Page-Sets

For the third page set, the template is run only once to produce one page, because there is no more data for loop 1 and it is therefore skipped entirely. Loop 2 runs without break till the end of the third data streams for this one page.

Since all data streams must be used for in-loop fields, the template is run again to produce the fourth page set, which again has only one page. Like the previous page set, loop 1 is entirely skipped and loop 2 is repeated to use all data in the last data streams. Since there are no fourth data streams for out-loop fields, they are again handled according to the job's "Outloop fields data loop back" option setting.

To learn more about the loop tags, you are advised to study our examples, which are included in the Mergemill Pro software package: Mergemill Pro > Mergemill Resources > Examples > English.

spacer

Content Field

Expression

Looping

Branching

System Values

Statistics

Sections

Example

spacer

Top of Page

Featuresspacer::spacerDownloadsspacer::spacerBuy Nowspacer::spacerSupportspacer::spacerTutorialsspacer::spacerTags Guidespacer::spacerSite Map


Copyright © 2001-2017 Cross Culture Ltd. All Rights Reserved.