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:
|
WIZLOOP plays a role in the following VTML-driven tools:
WIZSET can occur only within a TAGLAYOUT section or in a Wizard TEMPLATE.
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".
<WIZLOOP INDEX="parameter_name" FROM="beginning_value" TO="ending_value" STEP="increment"> ... WIZML code to execute ... </WIZLOOP>
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. |
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.
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".
<WIZLOOP CONDITION="expression">
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. |
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.
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.
<WIZLOOP INDEX="index_name" LIST="list_items"> ... </WIZLOOP>
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. |
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>
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:
<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>
When HomeSite or ColdFusion/JRun 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.
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.
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.
<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>