Let’s take a quick look at this tiny but very useful function.

You’ve probably noticed by now that a lot of xmerge items can be useful in a very basic manner right through to the complex. The range() function is no different and this article is well worth a read if you’re looking to make your templates that bit shorter, quicker to build and easier to maintain going forward.

Range life

Essentially all the range() function does is generate a list of integers based on the arguments provided:

range(count end): outputs a series of whole numbers up to the number you specified, less 1. Remember list indexes start at zero and so does this:

<:=range(3):> # [0,1,2]

range(count start, count end): specifies the number at which to start the generation:

<:=range(10, 13):> # [10,11,12]

range(count start, count end, step): specifies the number at which to start the generation, which to end and a pattern for stepping through the range:

<:=range(10, 20, 2):> # [10,12,14,16,18]

That’s the basics of how it works. Generally its use in a for loop is where you’ll start to see the benefit. Bonus points to anyone who knows where the heading of this section comes from.

Range and the for loop

Because range generates a list, we can use that to iterate or loop over. You might commonly see it written like this:

<:for i in range(0, 3):>
<:=i:>
<:end:>
# 0
# 1
# 2

That’s how its typically found, but as you’ll see if you try and type that in a word template more often than not ‘i’ will be autocorrected, so perhaps try something like ‘num’ or ‘count’ for your iterator (or whatever you feel let’s your coding tell a story and be readable for others).

In a list context you can use it similar to enumerate, except that it gives you more control over the ordering and extent.

<:for num in range(0, len(myList)):>
<:=myList[num]:>
<:end:>
# list item 0
# list item 1

Putting it to use

With some financial planning templates, most commonly fact finds, you may have sections or the entire document where:

Output blank rows so that the document is still whole and the client can see there is no data recorded for an area (reverse fact finds)
Output additional blank rows so that the client can update or add in any additional information (reverse/review fact find)

So with range() used in a loop we could instead iterate over 1 blank row – as many times as we want – instead of writing them all out again and again.

A pretty common example of a fact find section, where the tables and rows are unnecessarily duplicated:

Xplan Xmerge, Xplan Coding — Common example of duplication of the table and or blank rows commonly seen in fact finds and the like

.
We can instead put it all together to reduce our coding, length of document and items we have to format (now and later on):

Xplan Xmerge and Xplan Coding — All in one

The output above will give the same result as the first, both when there is data and when there is none.

In the above version we are using the additional currency arguments talked about here, to account for whether the client wants $0 to appear or if they just want it blank (change blank_zero to true)
If we also used our knowledge from lists we could start to reduce the coding and table rows down even further.
If we wanted to include some blank rows regardless of whether there is data or not (reverse/review) we would just remove the if len statement, else and end.
You can also set up a variable so that if the client has data, perhaps only 2 rows merge out (for where you want to allow rows for the client to add additional items) and if there is no data, maybe 4 blank rows merge etc.

Xmerge examples discussed above

Conclusion

Quick and simple.

Saving on blank rows might not seem like much but over the course of an entire fact find or discovery document, it adds up. Whilst there are advantages of doing things this way during construction, its the ongoing or future maintenance where things like this can have a major benefit and where steps taken to reduce unnecessary duplication of tables or rows is going to make life easier.