Your guide to basic xmerge variables: what are they?
what can they do?
May 10, 2015 | matthew-townsend
Variables can change the way you think and go about your coding
It’s important to get your head around variables, they are common place in many templates these days and they are an essential building block to improving your coding knowledge and your code in general.
Some of their benefits include:
- Reducing repetition of code
- Adding in redundancy to your coding calls
- Making complex conditioning and data calls easier
- Helping you to manipulate the data to get and show what you want
So what is a variable
Variables are any value or piece data that has been assigned – and is now stored in the coding and then executed in the merge process of your templates. They are defined in the coded template themselves which means unlike the data you call from xplan which is immutable your variables are dynamic and can be changed, updated or overwritten.
Creating a variable
In XPLAN we know double equals (==) is for comparing data, single equals is for assigning data. Therefore to create and define a variable, we simply use a single equal (=). For example, the following is defining a variable named “numbers”:
<:let numbers = 100:>
The item to the left of the equals sign is the variable name, in our example above our variable is called ‘numbers’. To the right of the equals sign is our data or value, in this case the number ‘100’.
More examples of this:
<:let number1 = 10:>
<:let number2 = 20:>
<:let calculation = int(number1+number2)/2:>
Above we created 3 different variables (“number1”, “number2”, “calculation”), I can call them anywhere throughout my template as needed including in sentences, such as below:
“Dear John, you recently told me your favourite number was <:=number1:> and your second favourite was <:=number2:>. I can add and divide these to get <:=calculation:>.”
Now that sentence is not a very good practical example of where we might use these but it does show how easily they can be inserted into your template and called.
Lets look at a practical and common example:
<:let total_net_income = float(($client.total_income.value+$partner.total_income.value)-($client.total_expense.value+$client.total_expense.value)):>
This variable is cleanly and aptly named “total_net_income” and can now be called and utilised any time throughout my document to reduce repetition coding and calculations but also make the overall coded document easier to read:
<:if total_net_income > 0:>Combined you have a cash flow surplus of $<:=currency(total_net_income, 0):><:else:>Combined, you currently have no surplus cash flow<:end:>
You can imagine how clunky the full net income calculation would be if used in that sentence but by using a variable, our conditioning and our sentences are all cleaner and easier to read. Most importantly though we can call and use that “total_net_income” again and again throughout the template.
Second variables example
By defining variables at the start of the template or when its first to be called, we can carry over a variable throughout an entire document to make things even easier and cleaner.
Naming is one of the most basic examples of where we can see clear benefits:
Often clients will want to use preferred name when referencing individual client and partners to make the document feel more personalised. Due to poor data, a problem with this in the past arose as a lot of clients may not have had preferred names for everyone. Coding a document to use preferred name where there isn’t one would then mean your document shows no name where one would be expected >.<
While this has improved and in general there should be no blank preferred names these days, it is a good example to look at for using variables and getting the best of two worlds – ease and redundancy.
<:let clientName = $client.first_name:><:if $client.preferred_name:><:let clientName = $client.preferred_name:><:end:>
<:let clientName = $client.entity_name:>
Let’s breakdown the above:
- We’ve defined a variable named “clientName“. Best of all it’s labelled clearly and obviously so you – and anyone else – will know its a variable for clients name.
- Notice how variables are case sensitive
- Its a lot quicker and easier to type clientName than it is the full code and conditioning above each time.
- We defined initially declared clientName with a value of $client.first_name because a) for individuals there will always be a first name b) if there’s no preferred name this is the name we want to show.
- Only if there is a preferred name will our variable be overwritten to show preferred name, otherwise it will stay as first name.
- We’ve added redundancy by not only checking and catering for preferred name and having a backup but by handling entities as well. We could now use <:=clientName:> throughout our document and be guaranteed an output at all times via that one piece of code rather than 3 individual pieces to cater for 3 different outcomes.
Third Variables Example
Variables can also provide an alternative path for how we can get the data we want.
Lets consider an asset table that only includes specific assets, something you sometimes find in advice documents and fact finds (broken up by asset type):
Because we are targeting specific assets and because the document could be for client/partner we can’t use the $client.total_assets coding. We are likely to write at least 2 if statements summing up those groups for those conditions – in that space it’s going to appear convoluted.
What if we built a running total of what appears on the page – as we’re iterating (looping) through all our assets.
- At the start, we defined our variable as 0.0 so it sets “total_assets” as a floating number (decimals).
- When the assets group is being iterated over, based on our conditions, our variable is saying “let total_assets equal whatever total_assets already equals PLUS this new amount“.
- You can see our total line is much cleaner than any alternatives and it ensures the total amount will only ever equal to the data that merges out.
When to use a variable
There really isn’t a hard and fast rule on this other than to consider if a variable is needed: is it the best solution and will it make your and the next persons task easier?
Like anything it requires balance and thought.If we look at our ‘clientName’ example though its easy to see the benefit of this approach:
- It’s going to be used a lot throughout the document (or multiple docs)
- It adds redundancy to your documents, catering for preferred, first and entities. Less potential errors and fuss for users the better (in most cases)
- Using this prevents unnecessarily duplication of coding that can otherwise occur.