WIZLOOP, WIZBREAK and WIZCONTINUE

The WIZLOOP tag controls repeated execution of WIZML statements

Looping is a very powerful programming technique that lets you repeat a set of instructions or display output over and over depending on whether a set of conditions are met. WIZLOOP supports three different types of loops: Index loops, conditional loops and looping over a list. The type of loop is determined by the attributes of the WIZLOOP tag.

The following subjects are covered in this document:


Related information about VTML and WIZML:

Tutorial
The Visual Tool Markup Language (VTML)
Reference
VTML reference - overview
Context
The WIZML Language
TAGLAYOUT
Container for
WIZIF
WIZINCLUDE
WIZLOOP
WIZSET

top

Tools

WIZLOOP plays a role in the following VTML-driven tools:

  1. Tag Editor
  2. Wizard

top


Location

WIZSET can occur only within a TAGLAYOUT section or in a Wizard TEMPLATE.

top


Index loops

Function

An index loop repeats for a number of times determined by a range of numeric values. Index loops are commonly known as FOR loops, as in "loop FOR this range of values".

Syntax

<WIZLOOP INDEX="parameter_name"
         FROM="beginning_value"
         TO="ending_value"
         STEP="increment">
    ...
    WIZML code to execute
    ...
</WIZLOOP>

Attributes

INDEX Required. Defines the parameter that is the index value. The index value will be set to the FROM value and then incremented by 1 (or the STEP value) until it equals the TO value.
FROM Required: integer The beginning value of the index.
TO Required: integer The ending value of the index.
STEP Optional: integer. Default is 1. Sets the value by which the loop INDEX value is incremented each time the loop is processed.

Examples

In this example, the INDEX variable is incremented for each iteration of the loop. The following code loops five times, displaying the INDEX value of the loop each time:

<WIZSET NewLine=Chr(13) & Chr(10)>
<WIZLOOP INDEX="LoopCount"
         FROM=1 TO=5>
The loop index is $$LoopCount.$$NewLine
</WIZLOOP>

The result of this loop looks like this:

The loop index is 1.
The loop index is 2.
The loop index is 3.
The loop index is 4.
The loop index is 5.

In the previous example, the STEP value has a default value of 1. But you can set the STEP value to change the way the INDEX value is incremented. The following code counts backwards from 5:

<WIZSET NewLine=Chr(13) & Chr(10)>
<WIZLOOP INDEX="LoopCount"
         FROM=5 TO=1
         STEP=-1>
The loop index is $$LoopCount.$$NewLine
</WIZLOOP>

The result of this loop looks like this:

The loop index is 5.
The loop index is 4.
The loop index is 3.
The loop index is 2.
The loop index is 1.

top


Conditional loops

Function

A conditional loop iterates over a set of instructions while a given condition is TRUE. To use this type of loop correctly, the instructions must change the condition every time the loop iterates until the condition evaluates as FALSE. Conditional loops are commonly known as WHILE loops, as in "loop WHILE this condition is true".

Syntax

<WIZLOOP CONDITION="expression">

Attributes

CONDITION Required. Sets the condition that controls the loop. The loop will repeat as long as the condition evaluates as TRUE. When the condition is FALSE, the loop stops.

Examples

The following example increments the parameter "CountVar" from 1 to 5. The results look exactly like the Index loop example.

<WIZSET NewLine=Chr(13) & Chr(10)>
<!-- Set the variable CountVar to 0 -->
<WIZSET CountVar=0>
<!-- Loop until CountVar = 5 -->
<WIZLOOP CONDITION="CountVar LTE 5">
    <WIZSET CountVar=CountVar + 1>
The loop index is $$CountVar.$$NewLine
</WIZLOOP>

The result of this loop would look something like:

The loop index is 1.
The loop index is 2.
The loop index is 3.
The loop index is 4.
The loop index is 5.

top


Looping over a list

Function

Looping over a list offers the option of walking through elements contained within a variable or value returned from an expression. In a list loop, the INDEX attribute specifies the name of a variable to receive the next element of the list, and the LIST attribute holds a list or a variable containing a list.

Syntax

<WIZLOOP INDEX="index_name"
         LIST="list_items">
    ...
</WIZLOOP>

Attributes

INDEX Required. Defines the parameter that is the index value. The index value will be set to the the next element of the LIST value on each iteration.
LIST Required. The list items in the loop; this must be a quoted, comma-separated list of items.

Examples

This loop will display the names of each of the Beatles:

<WIZSET NewLine=Chr(13) & Chr(10)>
<WIZLOOP INDEX="ListElement"
         LIST="John,Paul,George,Ringo">
$$ListElement$$NewLine
</WIZLOOP>

top



Nesting loops

The tags contained within the boundaries of a WIZLOOP can also be other WIZLOOP constructs. In this case, the inner loop executes from start to finish as many times as the outer loop executes. Loops can be nested as deeply as you like. Here the inner loop executes on each iteration of the outer loop for a total of 15 times:

Examples

<WIZSET NewLine=Chr(13) & Chr(10)>
<WIZLOOP INDEX="OuterLoopCount" FROM=1 TO=3>
Outer loop $$OuterLoopCount$$NewLine
    <LOOP INDEX="InnerLoopCount" FROM=1 TO=5>
    Inner loop $$InnerLoopCount$$NewLine
    </WIZLOOP>
</WIZLOOP>

top


Breaking out of a loop: <WIZBREAK> and <WIZCONTINUE>

When HomeSite or ColdFusion Studio encounters the WIZBREAK tag in a loop, it terminates the execution of the loop and proceeds to executethe WIZML code starting with the line immediately following the end of the loop. This is generally less elegant than constructing the loop with an appropriate conditional, but there are times when breaking out of a loop can simplify a WIZML code structure that's complicated or deeply nested.
When the program encounters the WIZCONTINUE tag in a loop, it skips the execution of any further code within the loop and moves on to the next loop iteration.

Examples

The following example isn't a terribly good use of WIZBREAK, but it shows the tag in action:

<WIZSET NewLine=Chr(13) & Chr(10)>
<WIZLOOP INDEX=LoopCount FROM=1 TO=100>
The value is $$LoopCount.$$NewLine
    <WIZIF LoopCount EQ 7>
        <WIZBREAK>
    </WIZIF>
</WIZLOOP>

The result would look something like:

The value is 1.
The value is 2.
The value is 3.
The value is 4.
The value is 5.
The value is 6.
The value is 7.

top



Putting it all together

Here's a more involved and realistic example, taken (and slightly adapted) from Control.vtm.

The purpose is to write out the value of the variable dropWidth (one of the controls in the Control visual editor) with or without quotes depending on whether or not the value is numeric. When it's numeric (consisting of only digits), no quotes are needed; in every other case quotes are written around the attribute value.

The example uses two nested loops: the outer loop is a conditional loop while the inner loop shows looping over a list; both use <WIZBREAK> to break out of the loop as soon as character is determined to be numeric (inner loop) or to stop looking any further when a non-numeric character has been found (outer loop). Note that the outer loop could also have been written as as an indexed loop; in this case there is no difference, I wrote it like this just for convenience while developing the IsNumeric code.

Three string functions are used: the expression Len(Trim(var)) contains two nested functions to determine the length of the variable (ignoring surrounding spaces) while Mid(var,CharIndex,1) gets the current character while looping through the characters of the variable.

Note: with the introduction of WIZML 2 there is now also an IsNumeric() function. Since the VTML Tag Definitions are (for now) designed to be compatible with WIZML 1 (so they can still be used in HomeSite or ColdFusion Studio 3.x), this is not used yet. With this function, most of the code shown below (which you will find in many places in several VTML Tag Definitions) would not be necessary.

Examples

<WIZIF dropWidth NEQ ''>
    <WIZSET var=dropWidth>
    <WIZSET CountLen=Len(Trim(var))>
    <WIZSET CharIndex=1>
    <WIZLOOP CONDITION='CharIndex LTE CountLen'>
        <WIZSET IsNumeric='false'>
        <WIZSET Char=Mid(var,CharIndex,1)>
        <WIZLOOP INDEX=Digit LIST='1,2,3,4,5,6,7,8,9,0'>
            <WIZIF Char EQ Digit>
                <WIZSET IsNumeric='true'>
                <WIZBREAK>
            </WIZIF>
        </WIZLOOP>
        <WIZIF IsNumeric EQ 'false'>
            <WIZBREAK>
        </WIZIF>
        <WIZSET CharIndex=CharIndex + 1>
    </WIZLOOP>
    <WIZIF 1>$$SpacingGap$${DefaultCase('WIDTH')}</WIZIF>
    <WIZIF IsNumeric EQ 'true'>=$$dropWidth<WIZELSE>="$$dropWidth"</WIZIF>
</WIZIF>

top