The While Loop

The while loop is used in situations where the number of required loop iterations is unknown. The number of loop iterations is decided by a user's answer to a question within each iteration of the loop. For example, you might want to ask the user to enter some income details and at the same time, ask whether the user has any more income to enter. This could be achieved with a loop like this:

Figure 1. While Loop

<loop loop-type="while" loop-expression="hasMoreIncome" 
entity="Income">
  <question-page id="IncomePage">
    <cluster>
      <question id="type">
        <label id="Type.Label">
          <![CDATA[Type:]]>
        </label>
      </question>
      <question id="amount">
        <label id="Amount.Label">
          <![CDATA[Amount:]]>
        </label>
      </question>
      <question id="hasMoreIncome" 
              control-question="true" 
              control-question-type="IEG_BOOLEAN">
        <label id="ContinueQuestion.Label">
          <![CDATA[More income?]]>
        </label>
      </question>
    </cluster>
  </question-page>
</loop>

The while loop will always perform at least one iteration (which makes it more of a do-while loop in programming parlance). If you have a situation where you want to check whether to go into the loop at all, then it should be wrapped in a condition.

The while loop suffers from the same complication as the for loop when it comes to going back though the loop when information has already been entered. It too effectively becomes a for-each loop up to the point at which the user has iterated through all the previously entered records. The while loop also requires the entity attribute to be set (as in the above example) and gives you the option of specifying a criteria.

Loops can be nested inside other loops and one of the most common usages of the while loop is to nest it inside a for-each loop. To extend the above example, multiple people might already have been captured by the time the income loop is reached in the IEG script. To capture multiple incomes per person, assuming the user has already been asked which persons have any income, the nested loop would look something like this:

Figure 2. Nested Loop

<loop loop-type="for-each" entity="Person" 
criteria="hasIncome==true">
  <loop loop-type="while" loop-expression="hasMoreIncome" 
    entity="Income">
    <question-page id="IncomePage">
      ...
      <cluster>
        ...
        <question id="hasMoreIncome" 
                  control-question="true" 
                  control-question-type="IEG_BOOLEAN">
          <label id="ContinueQuestion.Label">
            <![CDATA[More income?]]>
          </label>
        </question>
      </cluster>
    </question-page>
  </loop>
</loop>

It is recommended when using while loops that the loop expression should be a simple expression referring just to the id of a question that is asked inside the loop to determine if more records should be added. This question should be a control-question of type Boolean.

The control-question will be updated automatically when adding or deleting a record through the summary page. When reviewing the answers by going through the loop after the initial pass, the question will be read-only, except on the last iteration, to provide the opportunity to add more entities.