What is new in RPE 1.1.2 – Loops


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 term is borrowed from programming languages and reflects how the property is interpreted by RPE. See the quote from Wikipedia:

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.
Advertisements

Author: Dragos Cojocari

Architect for Rational Publishing Engine

12 thoughts on “What is new in RPE 1.1.2 – Loops”

  1. I have a problem with the loop condition. When I create a container, I can’t see the do-while condition in the property of this container. Do I have to change any setting?

  2. i get lost at this point.. is the graphic and script correct on this section?
    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

  3. Hey Michael,

    the graphic and scripts are correct but what is misleading is the lack of context:
    – the first script screenshot is the code for the “do while condition”
    – the second script screenshot is the code for the assignment to currentAuthor_ . The code gets the head of the author list and assigns it to the currentAuthor_ variable
    – the third script screenshot is the code for the assignment to the authorList variable. The code gets the tail of the author list and assigns it to the authorList variable

    So even though the 2nd and 3rd script operate on a single variable, authorList, the result of their evaluation is assigned to different variables: first to currentAuthor and then to authorList.

    With RPE 1.2.1 the 2nd and 3rd scripts could be merged into a single JavaScript code block which is clearer:

    var pos = authorList.indexof( “,”);
    if( pos >= 0)
    {
    currentAuthor_ = authorList.substr( 0, pos);
    authorList = authorList.substr( pos+1);
    }
    else
    {
    // last author
    currentAuthor_ = authorList
    authorList = “”
    }

  4. Hi Dragos,

    I have been using iteration blocks well up until this point, it is a very useful bit of functionality.

    I notice that the contents of an iteration block will ALWAYS be published at least once, regardless of the do-while statement. To test this I made a template where a variable ‘condition’ is set to false, and then an iteration block where the do-while statement is set to ‘condition’. The iteration block is entered once.

    Once this behaviour is known it is easy to apply a condition to the iteration block (in my example above, set ‘condition’ as a condition). However it took me a while to realise this behaviour as it differs from the programming languages I’m familiar with (inc. JavaScript!).

    Might I suggest that it is made clear that this is the behaviour of the iteration block, to avoid confusion?

    Best Regards,

    Sam

    1. Hey Sam,

      thanks for your comment. I have tried to explain this using the quote from Wikipedia in the article: “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…. the control structure is often also known as a post-test loop”

      However your phrase, “the contents of an iteration block will ALWAYS be published at least once, regardless of the do-while statement” is clearer. Would you mind if we borrow it for our Infocenter content?

      Regards,
      Dragos

  5. Oh crikey, I apologise. I thought I’d read this article properly before posting, but I must have skipped over that quote.

    Thanks for responding so quickly and by all means use my words, but I take back my comment! I think the wiki quote is very clear. What needs correcting is my eyes filtering out grey text!

    Regards,
    Sam

      1. Have got the iteration to work with a variable containing a list of Functional Areas (e.g. PM,Eng,Procurement,…..) but anything within the iteration loop which uses a Query only runs once. Is there anyway to get the query to repeat as I am trying to produce a series of tables based on an attribute value. Didn’t really want to call up the template multiple times, once for each attribute value.

        E.g. trying to produce a table for all objects with a Functional_Area of PM, then another table for all objects with a Functional_Area of Eng etc….

  6. Ok, sorted that. As per suggestion in article (sorry missed it before) I added a Container with a Data Source Configuration before the Container containing the Queries and it now reloads the data source and runs the modified query for each iteration. The Data Source Configuration just needs to contain the name (in formatting->data->taget data source) of the data source as it appears in the Data Source Schema tab (in my case “DOORS 2”).

    1. Darren, Hi. I’m trying to do the same as you in RPE but can’t seem to get it to work! It all worked fine in previous versions of RPE but now i’m using 1.2.1.1, i need to move the query to iterate round just the row of the table rather than round the whole container (containing paras, headers & the table). I also want to produce a table for each possible setting of the attribute Functional Area – what ‘modified query’ do you use to iterate round for your table row?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s