UPDATE: the example template is available here [RPE DevWorks Community Library].
In many cases you need to repeat a certain block in your template. This can already be done if you iterate data but sometimes it can be useful to do it when you do not have data to iterate over. You can achieve this in RPE by duplicating that template section but that is not desirable for two reasons:
- duplication is evil
- duplication works only if you know the number of times you want the block to be repeated
Some examples of scenarios in which this function is required.
- create a table from data provided by user at runtime such as an author list
- group data based on an attribute, for example list the workitems split in 3 groups: all defects, all enhancements and all tasks.
Note: you can do this by using the same template multiple times in the docspec but it has the overhead of configuring the data
- follow links from data sources when those links are returned in a single element hence the normal data source based iteration will not work.
RPE 1.1.2 provides the means to repeat template blocks when the iteration is not based on data source results. This new feature is implemented through the new property available for containers called “do-while-condition”.
The do while construct consists of a block of code and a condition. First, the code within the block is executed, and then the condition is evaluated. If the condition is true the code within the block is executed again. This repeats until the condition becomes false. Because do while loops check the condition after the block is executed, the control structure is often also known as a post-test loop. Contrast with the while loop, which tests the condition before the code within the block is executed.
Simply put the iteration block will always be published at least once, regardless of the do-while statement. (Updated 2015.01.13)
LIMITATION: queries inside a loop container will be executed only once. To have the queries executed multiple times use a Dynamic Data Source Configuration element inside the loop container to force the queries to be reinitialized.
NOTE: RPE will ignore “do while conditions” that are set using the “Simple Value” property to avoid infinite loops. But there is nothing to prevent you from using a script expression that always evaluate to true hence causing an infinite loop. So make sure that the expression you use for the “do while condition” will evaluate to false after a finite number of passes.
Create a table from data provided by user
This is a discussion on the first usecase described above, generating a table of authors from information provided by the user. The output should look like this:
The user will provide the list of authors in a single variable separated by comma such as: Dragos Cojocari, John Doe, Jane Doe. The template looks like this:
Now for how it works: the solution relies on using the “do while condition” property of the container and update the “authorList” variable on each iteration. The second part is crucial not only to get the right results but also to avoid infinite loops. The order of assignments is also important, the current author is calculated before the authorList is modified.
- the user provides the list of authors in the authorList variable
- the table will be displayed only if the authorList is not empty ( the condition on the table)
- the LOOP container has the “do while condition” property set to this
- the “Get current author” has an assignment for the “currentAuthor_” variable which calculates the first author name from the list to be used in the current row
- the “Remove first author from the list” container has an assignment for the “authorList” variable that removes the first author from the list. This will ensure that the loop doesn’t go forever.