Xmerge Coding – Variables

Xplan Xplained

Your guide to basic variables: what are they?
what can they do?

Variable basics

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 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 (or assigned values) are any value or data that has been assigned and is now stored in the coding and then executed in the merge process of your templates.  They can be called many times and unlike the standard xplan data you call (which is immutable) your variables can be changed, updated and modified – they are dynamic and fluid.

How do we create a variable?

In xplan we know double equals (==) is for comparing data, single equals is for assigning data.  To create and define a variable we simply use a single equal (=)  For example <:let numbers=100:> is a variable.

The item to the left of the equals sign is the variable name, in our example above our variable is named ‘numbers’.  To the right of the equals sign is our data or value, in this case the number 100.

Further basic examples of this:

<:let number1 = 10:>

<:let number2=20:>

<:let calculation=int(number1+number2)/2:>

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:>

From the above we have created 3 different variables (number1, number2, calculation), you can see I can call them anywhere including in sentences and I can use variables to manipulate data and other variables as we did (in a basic example) with calculation.

Now that’s not a very practical example for what we do for our clients and what they want in their templates but hopefully you’re starting to get how variables are structured and what they can do.  Lets look at a more practical example:

<:let total_net_income=float(($client.total_income.value+$partner.total_income.value)-($client.total_expense.value+$client.total_expense.value)):>

So this variable is cleanly and aptly named ‘total_net_income’ and can now be recalled and conditioned any time throughout my document reducing repetitive calculations and making parts 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 were all cleaner and easier to read most importantly though we can call and use that net_total_income again and again in the same document.

Second Example

Variables can be used to make coding easier, by defining it at the start of the document or when its first to be called we can carry over a variable throughout an entire document.  Naming is one of the most basic examples of where we can see clear benefits:

Often templates (and clients) will want to use preferred name when referencing individual client and partners.  Even though changes in xplan (when adding a client) mean that preferred name will no longer appear blank (the first name is automatically inserted) there is still a lot of clients with historical records where preferred name could be blank so just calling <:=$client.preferred_name:> and is not a very robust choice.

Using variables though we can have the best of both worlds and additional redundancy:

<:if $client.is_individual:>

<:let clientName=$client.first_name:><:if $client.preferred_name:><:let clientName=$client.preferred_name:><:end:>

<:else:>

<:let clientName=$client.entity_name:>

<:end:>

In the above:

  • The variable name in play is ‘clientName’.  It is labelled clearly and obviously so you and anyone else will know its a variable for clients name.  Note:  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 clientName initially as $client.first_name because a) for individuals there will always be a first name b) if theres 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 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).

Xplan Xmerge Coding - Variables 1

In the above example, 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 and 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 through all our assets.

Xplan Xmerge Coding - Variables 2

  • 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 line’s item 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:

  • 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 repeating that would occur as a result of wanting to use this approach and not using variables.

Like anything it requires balance and thought

Remember

To give your variables clear and easy to understand names (as much as possible).  Also make sure your variable is always defined!  If your variable sits or is used nestled within conditioning, consider defining it first up.

Matthew Townsend
Xplan Consultant and Developer | Wealth Management Technologist at Create Something
Matthew is an experienced and innovative Xplan consultant and developer, having worked on and developed some of the largest advice projects in the industry. Passionate about building great experiences in xplan that enable businesses and clients to get the most out of this powerful software.

Matthew Townsend

Matthew is an experienced and innovative Xplan consultant and developer, having worked on and developed some of the largest advice projects in the industry. Passionate about building great experiences in xplan that enable businesses and clients to get the most out of this powerful software.

This Post Has 2 Comments
  1. Helpful advice. It’s the little changes and improvements that lead to import changes and better coding in future works. Thanks

  2. I updated our templates last week and your post made the naming much easier.

    +1 for clear variable names!!!

    Have some questions from some of your other blog posts will just email through if that’s okay.

    Thanks,Nat

Leave a Reply

Your email address will not be published. Required fields are marked *