Repeated Region Builder

Repeated Region Builder

In this topic ...

Quick Tips
Specifying Inputs
Using Repeated Regions in a Web Application
Related Topics ...

Overview: Creating Forms
HTML Guidelines
Passing Arguments to Actions

Use the Repeated Region builder to repeat part of an HTML page. Both the HTML and (the effect of) the control builders that affect controls within the block are repeated. We can repeat a section a fixed number of times. Repeated Region duplicates a block of HTML once for each element in a list. It is very tolerant about which fields you fill in. If you specify a Counter Variable, then it will keep track of the count and make it available to you, whether or not you are repeating based on a count or just repeating for all the elements in a list.
This builder will correctly eliminate the block if the repeat Variables result in no iterations. For example, if you provide it with an empty list, or if the End Count and Start Count fields evaluate to From 1 to 0, nothing from inside the repeated block will be displayed.

Quick Tips

For information on how to pass data within a repeated region, see the online help topic, "Using InputMappings for Builder Calls in a Repeated Region."
The Start Count and End Count inputs can be used to display a set number of "rows" at a time. For example, if there are 20 elements in the structure and you want to display five of them at a time, you could create Next and Previous buttons that set the variables specified for the Start Count and End Count inputs to an appropriate value and then redisplay the page.
To use the Repeated Region builder effectively, have all of the following elements available within the model:

An XML variable that is populated with repeating data
A Loop variable in which to store each iteration of the data
HTML with elements to be repeated
Builders that display data from the loop variable onto those HTML elements. (The Dynamic Table builder is often used for this purpose.)

Specifying Inputs

The Repeated Region builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."

Input Name Description
Name Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Page Location Use the Page Location input to specify the page or pages on which this builder call will act.
See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Source Data The XML structure over which the repeated region will loop. We can use the Reference Chooser to select a variable or method that returns the XML structure.
We can also specify a method or Java expression that returns an object that implements java.util.Collection or an Iterator for a Java collection. See "Specifying Lists," for more information.
Loop Variable The variable you specify will be used to store each element as the block is repeated.
Use the select box to choose the name of the variable that will store the current XML structure. We can also enter a name for a new variable, which the builder call adds to the model when you click OK.
You can refer to the Loop variable in other builder calls with this notation:
"${Variables/LoopVariableName}"
Counter Variable
Counter Variable The variable you specify will be used to store the current number of repeated items.
Use the select box to choose the name of the variable. We can also enter a name for a new variable, which the builder call adds to the model when you click OK.
You can refer to the Counter variable in other builder calls with this notation:
"${Variables/CounterVariableName}"
(Optional) Start Count Enter one of the following:

A number at which to begin the repetition
A call out to the variable that will contain the number at which to begin the repetition, for example ${Variables/startrepetitionvariable}.

Typically you would create a method that would write the number to the variable.
The default value for the Start Count field is 0.
(Optional) End Count Enter one of the following:

A number at which to end the repetition
A call out to the variable that will contain the number at which to end the repetition, for example ${Variables/endrepetitionvariable}.

Typically you would create a method that would write the number to the variable.
If you specify a value greater than the number of items in the Source List, the Repeated Region builder goes through the items again until it reaches the End Count value.
Source Data Filters
(Optional) Skip this many elements The value you enter here defines the number of items skipped (from the beginning of the list) in the repeated region. Note that item numbering starts with zero.
Use elements named Specify the element names corresponding to the values you want to view. The builder filters out the rest of the elements.
For example, assume you have XML in a variable that contains many types of elements, as shown below:
<Locations>
 <City>New York</City>
 <Town>Grover's Grove</Town>
 <City>Boston</City>
 <Borough>Glen Ridge</Borough>
 <City>San Francisco</City>
 <Town>Plainville</Town>
 <City>Chicago</City>
</Locations>
If you only want the values assigned to the City element to be displayed, you would enter City in the Used elements named field.

Using Repeated Regions in a Web Application

When you are using this builder to duplicate a section of a page for each element in a list, provide three items of information: the section of the page to be repeated, the list to repeat over, and a loop variable. At run time, the loop variable is a placed in the Variables section where each element will be stored, one at a time, as the block is repeated. We can view the Variables section in the Designer by clicking the WebApp view. Then, in the middle pane select WebApp | Variables. Under Variables, select the name of the loop variable. Its value at run time is displayed in the right pane.
Consider this example: Assume you have the following XML list, which you have obtained through a Service Call (perhaps a database query) and you have used an assignment operation to store in a variable named Result.
<Result>
<User>
<Name>Fred Flintstone</Name>
<Address>55 Slate Way</Address>
<City>Bedrock</City>
</User>
<User>
<Name>Wilma Flintstone</Name>
<Address>55 Slate Way</Address>
<City>Bedrock</City>
</User>
</Result>
The following HTML page is used:
<BODY>
<H2>Users:</H2>
<UL>
<LI name="RepeatSection">
name goes here
 
address goes here
 
City goes here
 
</LI>
</UL>
</BODY>
The builder uses the HTML tag of the control, which is the outermost part of the repeat. In this example, it is the <LI> tag that is being repeated. If you don't have a convenient tag for repeating, place a SPAN in your HTML and use that to demarcate the repeated area.
When specifying the Loop Variable, the prefix "Variables/" is optional. If you specify "Inputs/Name" as a variable, then you will end up with the value Variables/Inputs/Name.
In the Repeated Region builder dialog, you would specify Variables/Result as the List, and you might select theUser as the loop variable. The example HTML page shown above provides a bullet list of the names and addresses.
In the imported HTML, there is only a single bullet item. You want to repeat this entire section, once for each element in the list. To put the data in the repeated section, create Text builders which operate on the SPAN sections.
The first Text builder would be userName, and it would specify as its input Variables/theUser/Name. Note how the entire first list element (the portion within the User tag) has been put into the variable Variables/theUser. The first time this block is duplicated on the page, this variable contains the value "Fred Flintstone." The second time, it contains the value "Wilma Flintsone." After you add Text builders for userAddress and userCity, the final page, when rendered, resembles the following:
USERS:

Fred Flintstone
55 Slate Way
Bedrock NH
Wilma Flintstone
55 Slate Way
Bedrock NH

Repeating a Region a Fixed Number of Times

The second use of this builder is to repeat a fixed number of iterations. To do this, fill in the Start Count and End Count fields in the builder call editor of the builder. If you specify a value greater than the number of items in the Source List, the Repeated Region builder will re-iterate over the items until it reaches the End Count value. These values can come from the data sources (such as, Variables, Inputs, ServiceOutputs) if you prefix the source name with an $ sign.
If you enter field an indirect reference to a variable in the Counter Variable, the current value of the count is stored in that variable. This option is available whether you are repeating over a list or repeating a fixed number of iterations. For example, if you had specified ${Variables/theCount} as a counter variable in the above example, then it would contain "1" during the first iteration (when ${Variables/theUser/Name} contained "Fred Flintstone", "2" for the second iteration, and so on.
Tip - Keep the following in mind when specifying the loop and the count variables: The prefix "Variables/" is optional. If you specify "Inputs/Name" as a variable, you will end up with the value Variables/Inputs/Name.

Skipping Elements in a Repeated Region

This builder lets you skip a segment of a repeated region. The segment we can skip must be a contiguous segment, and it must start at the beginning of the region. The input titled, "Skip this many elements" is where you specify the number of elements you want to skip. For example, if you enter 5 in this field, the repeat operation will begin with element number 5. Elements 0, 1, 2, 3, 4 are skipped. Use this feature when you want to offset a repeat operation from the beginning of a repeated region.

Input Name	Description
Name	Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Page Location	Use the Page Location input to specify the page or pages on which this builder call will act. See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Source Data	The XML structure over which the repeated region will loop. We can use the Reference Chooser to select a variable or method that returns the XML structure. We can also specify a method or Java expression that returns an object that implements java.util.Collection or an Iterator for a Java collection. See "Specifying Lists," for more information.
Loop Variable	The variable you specify will be used to store each element as the block is repeated. Use the select box to choose the name of the variable that will store the current XML structure. We can also enter a name for a new variable, which the builder call adds to the model when you click OK. You can refer to the Loop variable in other builder calls with this notation: "${Variables/LoopVariableName}"
Counter Variable
Counter Variable	The variable you specify will be used to store the current number of repeated items. Use the select box to choose the name of the variable. We can also enter a name for a new variable, which the builder call adds to the model when you click OK. You can refer to the Counter variable in other builder calls with this notation: "${Variables/CounterVariableName}"
(Optional) Start Count	Enter one of the following: A number at which to begin the repetition A call out to the variable that will contain the number at which to begin the repetition, for example ${Variables/startrepetitionvariable}. Typically you would create a method that would write the number to the variable. The default value for the Start Count field is 0.
(Optional) End Count	Enter one of the following: A number at which to end the repetition A call out to the variable that will contain the number at which to end the repetition, for example ${Variables/endrepetitionvariable}. Typically you would create a method that would write the number to the variable. If you specify a value greater than the number of items in the Source List, the Repeated Region builder goes through the items again until it reaches the End Count value.
Source Data Filters
(Optional) Skip this many elements	The value you enter here defines the number of items skipped (from the beginning of the list) in the repeated region. Note that item numbering starts with zero.
Use elements named	Specify the element names corresponding to the values you want to view. The builder filters out the rest of the elements. For example, assume you have XML in a variable that contains many types of elements, as shown below: <Locations> <City>New York</City> <Town>Grover's Grove</Town> <City>Boston</City> <Borough>Glen Ridge</Borough> <City>San Francisco</City> <Town>Plainville</Town> <City>Chicago</City> </Locations> If you only want the values assigned to the City element to be displayed, you would enter City in the Used elements named field.