Manage the number of items in a repeat - XpressDox

When users enter repeating data into your XpressDox template, you can manage the number of occurrences of a repeater.

“Repeaters” are otherwise called “complex elements” in XML, but are essentially items through which you can iterate using a «ForEach()» in the template. An example would be

My children are:

«ForEach(Child)»
Name: «Name»
Age:  «Age»
«End()»

In general, XpressDox will allow the user to enter either no Child elements, or as many as they want to. But in certain circumstances you might want to either limit the number of a repeater to some maximum, or you might want a certain minimum number to be entered, or else a fixed number.  All of these are possible, using a number of different XpressDox features.

Ensure users capture at least 1 repeated item

Use the command «Required(Child)» to make sure that at least one Child is captured in the interview.

Note that the initial Child node in the desktop interview is put there for information to the user that <emChild information can be capture. If nothing is typed in that entry then it is ignored when XpressDox tests for existence of the node.

MaximumRepeats

Use the MaximumRepeats commands to limit the number of repeats captured in an interview.

Rule

Using a Rule command, you can apply either a maximum  or minimum, or both, to the number of repeaters captured.

1. Limit the number of Child elements to a certain maximum, for example 2:

«Required(Child)»
«ForEach(Child)»
Name: «Name»
Age:  «Age»
«End()»
«Rule(Child,hard,count(Child) <= 2,'No more than 2 children must be entered')»

Note the Required. This is needed to make sure that at least one Child is entered, otherwise, if no Children are entered, there will be nothing in the interview for the Rule to act on.

2. Make sure that a certain minimum number of Child elements are entered,  for example 2:

«Required(Child)»
«ForEach(Child)»
Name: «Name»
Age:  «Age»
«End()»
«Rule(Child,hard,count(Child) >= 2,'At least 2 children must be entered')»

Warn the user as they type

It can be frustrating to fill in an interview only to find that there is something wrong when you click on OK (or Assemble), when the Rule is fired. With commands like OnEnterSet it is possible to give visual feedback to the user immediately there is a problem.

1. Take the first situation – you want to limit the number of children to 2, and warn the user as soon as they enter too many Child elements. Have a look at this:

«ForEach(Child)»
Name: «Name»
Age:  «Age»
«Footing(Name,                        )»

«OnEnterSet(Name,Name,FootingText,(PositionOfRepeater() > 2),'You have exceeded the recommended number of children','                              ',EvenWhenNotEmpty)»
«End()»

The Footing and OnEnterSet commands would cause a warning to be issued to the user as soon as they try to enter a third or subsequent child.

Note that the value of the string in the Footing command, as well as the FootingText in the OnEnterSet for the case where the PositionOfRepeater is less than 2 must be a string of blanks long enough to contain the “You have exceeded …” message. The value set in the OnEnterSet is used for footings of the subsequent Child/Name items created in the interview. If you had specified an empty string in the OnEnterSet, then the subsequent Child/Name items would not get any footings created at all.