Xplan Quick Xplain
A look at using group items in a sentence
Looping through data in a sentence
From necessity to just want clients might want their templates
It can be necessary in many different instances to present group data within a sentence structure, as opposed to in a table or list, as you regularly would. Today we’re going to cover off the elements of how that works.
Common areas where this is done are around childrens names (dependants) or when the document is addressed to members, trustees and directors. Depending on the document and what the client wants to achieve there can be many more and the structure we’re going to cover today can be replicated for all of those uses.
Note: I will say at the outset there are more sophisticated ways to code this and we’re going to touch on some of those in subsequent articles. The way we use today though is the most common and is a great example that incorporates key concepts, such as the use variables and logic to achieve something we can’t natively do
What we want to do
Loop through a group and use the items (data) in a regular sentence.
Let’s say we have 3 children in the standard xplan dependants group: Jimmy, Johnny and Jane. We want to show these names correctly in a sentence. By default we could loop or iterate through the group using standard code eg:
You have <:=len($client.dependant):> children: <:for item in $client.dependant:><:=item.dep_name:> <:end:>.
# The result you should see would be ‘You have 3 children: Jimmy Johnny Jane.
There’s no appropriate punctuation that’s going to work using this standard approach (we need comma’s and and’s).
There are areas we need to achieve this for a personal touch, eg a letter addressed to the trustees of a self-managed super fund. It could say Dear Trustees, but it’s much more personal (and clients often want) to use their names.
Likewise, some clients just want or feel it’s more personal to add the children’s details via a sentence than a list or table. Simply, the ‘why’ ranges from necessity to clients preferences and how they might like to present data.
How we could go about this
The standard structure and code you a) might be used to seeing or b) will likely see, goes like this:
<:let i = 0:><:let x = len($client.dependent):><:if x > 0:><:for item in $client.dependent:><:if len($client.dependent) > 1:><:if i == x – 1:> and <:else:><:if i > 0:>, <:end:><:end:><:end:><:=item.dep_name:><:let i=i+1:><:end:><:end:>
In plain English lets walk through what’s happening with the above code.
- We’re defining i to equal zero so the variable is initialised and x is also defined as the total number of items in the dependents group (In our example this will set x to equal 3 (jimmy, johnny, jane)).
- We’re checking to see if x has a value, if there are no items in the dependants group x would be equal to zero.
- If there is even one item in x we will move on to the for item element and begin looping through the group.
- We’re then checking to see if there is more than 1 element in the group because if there is only 1 child we don’t need any additional punctuation.
- Because there is more than one child we’re now comparing (==) to see if i is equal to x minus 1. This is a countdown checker so that when we are on the last element it places ‘and’ before the final name. On the first loop through this will always return false.
- If the countdown comparison isn’t true it goes to the else and checks if i is greater than 0. If it is, it places a comma if not nothing happens. On the first loop this will also be false.
- Finally we add the childrens name into the sentence
- We then iterate the i counter by 1 and the loop returns to the start. On subsequent loops the i counter will return true for one of the two values it passed false on initially.
- In many instances you are likely going to check if there are items in the dependants group before you even start so you can remove some redundant coding like the purple x check.
- These are poorly named variables that don’t help anyone. We’ve kept them as i and x because that’s how this coding is likely to appear on templates you come across. At the very least try to avoid using i and other characters that Word will autocorrect the case on!
The end result we want is therefore:
You have <:let i = 0:><:let x = len($client.dependent):><:=x:> children<:if x > 0:>: <:for item in $client.dependent:><:if len($client.dependent) > 1:><:if i == x - 1:> and <:else:><:if i > 0:>, <:end:><:end:><:end:><:=item.dep_name:><:let i=i+1:><:end:><:end:>
By using variables and a bit of logical problem solving, we’ve achieved the desired result.
This same structure can then be applied to any area where you need to go through a loop or group data in a sentence.