skip to Main Content

Xplan Xplained

The power of
functions in Xmerge

building blocks of a powerful coding base

Let’s talk about a powerful programming concept.

Functions are going to let you take the next step in improving your coding and creating a solid design base that can be used throughout all your templates.   Some of the benefits of these include:

Reducing duplication of code

Increasing code reusability

Improving the clarity of your code

Consistency and error handling

Framework of a coding base for all your templates

Before you begin

It’s recommended to read the article on variables and single line conditioning before you proceed.

What is a function?

In general programming, functions are self-contained blocks of coding that perform a specific task.  One of the real key benefits of them, is that the task they perform can be dynamic and based on the parameters they hold and the arguments (data) passed to the function.

Already in xmerge you use many of the built in functions.  Lets look at the currency functions for example:

<:=currency($client.total_income.value, 2):>

  • Function name
  • argument 1 is the value or amount that will be output
  • argument 2 is the decimal places

So currency is performing a task for us behind the scenes and all we have to do is give it two arguments – reducing our work and we can use it over and over again.  We also have the benefit of knowing the currency function has optional arguments built in. 

For another example, you can see from this article what the backend of floatify essentially is.  it’s a lot easier to define it once and use it again and again, than having to redefine it every time.

Using them in Xmerge

In Xmerge we can’t create functions in the full sense of the word, but we can utilise lambda to create function equivalents, which still have the benefit of

  • reducing our code base
  • consistent coding
  • error resistant coding
  • help to create a set of common standards across all templates

The basic structure of lambda

Remember, the idea of functions is to be able to reuse the function, again and again, just with different inputs:

Function=lambda argument1: expression and or conditions using argument1

In practice:

<:let name=lambda x: str(x.preferred_name):>

Essentially what we have done above is:

  • Given our “function” the name…’name’
  • argument one, we’ve just called ‘x’.  Doesn’t really matter what value you specify for the parameter (argument), sometimes you might see val, but x, y, z are quite common
  • Whatever x is, the output value is going to return the preferred name

Putting it into a template:

<:=name($client):> & <:=name($partner):>
# Johnny & Jill

You can see the function returns the value based on the argument passed to it, in this case $client (x.preferred_name) or $partner (x.preferred_name) we get the desired result for each input.

Expanding on this

There’s a reason we did the article on ternary operators previously, because if we take the knowledge from that and apply it to our use of lambda, we can create a much more powerful name function that will account for all types and kinds.

<:let entityName=lambda x: str(x.preferred_name) if x.is_individual and x.preferred_name else str(x.first_name) if x.is_individual else str(x.superfund_name) if x.is_superfund else str(x.trust_name) if x.is_trust else str(x.company_name) if x.is_company else str(x.partnership_name) if x.is_partnership else str(x.entity_name):>

Whilst the above would lose points for readability, it packs a lot of positive trade offs:

  • Its highly functional, in that it will produce a result for every entity type;
  • It’s dynamic for each entity and their actual name (rather than just relying on x.entity_name) and its error resistant for individuals in the event they don’t have a preferred name;
  • Unlikely it would need to be changed;
  • Can be used across everything, letters to entire advice documents can reuse this function and this approach;


Thinking further

These articles are designed to arm you with the knowledge needed to do more with Xplan and Xmerge and to get you thinking about ways to reduce your code or make your coding easier to build, read and support.

Even though we’ve only given you a basic example, once you start to look at all your letters right through to advice documents you are going to find so many more things you can build a common framework around.  That framework is going to make coding all your stuff a lot easier, especially when you combine it with other approaches.

Back To Top