Xplan Xmerge Coding – All About Strings

Xplan Xplained

Your guide to working with Strings in Xplan

All about strings

Strings are one of the most common data types you will work with in Xplan and your Xmerge coding.

Examples of built in strings you have likely seen or used already include: the client’s name, address details and goal descriptions – all of those are stored and represented as strings.

Strings themselves may just be bits of text (made up of characters) but that doesn’t mean we can’t do a range of things with them to:

  • manipulate the data;
  • to increase consistency; and to
  • Get the data to appear (output) how we want.

Working with Strings

Whilst data like <:=$client.preferred_name:> may itself be stored as a string, we need to encapsulate it with the str class in order to manipulate it further.  An example of this encapsulation is: <:=str($client.preferred_name):>

In both cases the preferred name will appear exactly the same but using str encapsulation will allow us to do more as discussed below.

Basic built in methods

Method
.
What it does
.
  Code example
.
.title()

The first character of each word in a string will be capitalised.
If your data was “MACQUARIE CASH FUND” title would turn it to “Macquarie Cash Fund”

  <:=str($client.first_name).title():>
<:=str(row[‘description’]).title():>
.upper()

Returns the entire string as in uppercase format.
This can be useful for things like address where the town or state may not have always been stored in upper case, using this eliminates that inconsistency. Eg Sydney, nsw becomes SYDNEY, NSW

  <:=str($client.preferred_suburb).upper():>, <:=str($client.preferred_state).upper():>
.lower()

Returns the string as all lower case.
Probably most useful with custom strings but if you wanted to use the clients marital status in a sentence it would merge like this: Client, you are currently Married to… Using lower would turn this into: Client, you are currently married to

  <:=str($client.marital_status).lower():>
.capitalize()

Returns the first character only as capitalised, as opposed to title which will capitalise the first character of every word in a string: “MACQUARIE CASH FUND” would become “Macquarie cash fund”

  <:=str($client.preferred_name).capitalize():>
.swapcase()

Swaps the existing case of the string with the opposite (anything lower will become upper and vice versa)

eg ‘Sydney’ in swapcase would return as sYDNEY.

I cannot think of a time when I have ever used this but it could be a great trick if you want to bug your end users

  <:=str($client.preferred_name).swapcase():>

Advanced built in methods

Method
.
What it does
.
Code example
.
.strip()

Removes white space from both start and end (left and right) of a string.

Not as sexy as it sounds but straight forward; strip in its native form will simply remove any white space. If by chance you had data or a string stored as“102 Queen St “, strip would turn that into “102 Queen St” eliminating the white space we saw to the right of St. Not commonly needed as in most instances when you save data in Xplan it removes white spaces but there are instances where it doesn’t and this can come in handy for error redundancy.

  <:=$client.preferred_address.strip():><:if len(str($client.comments).strip()):>Yes comments exist <:end:>
.strip(‘x’)

x here represents any leading characters you want to remove from the string.

Strip isn’t just used to remove white space, by defining characters within this method it will remove the leading character of that type.

A classic example of this is where a string field may have been used for entering a dollar amount. There are plenty of areas in xplan where numbers and amounts may be stored as string data, you can still convert it to a floating number and manipulate the amounts…BUT..the issue is where users might add a dollar sign to their data entry eg instead of just entering 500 the user enters: $500.00.This is problematic for your output as you might be using a static dollar sign so now you will get $$500.00 appearing. it will also cause any mathematical manipulation to fail. So strip provides the solution such as: <:=str(float($client.remuneration_amount)).strip(‘$’):>

 

  <:=str(float(item2.benefit_amount)).strip(‘$’):>
.lstrip()

Works the same as strip however it only removes leading characters from the left.

Commonly you may see this used with date coding for example. <:=datetime_merge.format(‘%d’):> would return a value of 03 if run on the third of January but chances are you just want your date to display as 3 January not 03.

Using the lstrip function will remove the first left 0

  <:=str(datetime_merge.format(‘%d’).lstrip(‘0’):>
.rstrip()

As above but looks for the leading characters from the right of the string.

   
.replace(‘x’, ‘y’)

Looks for and replaces one defined character with another. .replace(‘x’, ‘y’) where x = the character you want to find and y = the character to replace it with. To replace it with white space y can equal ‘ ‘ or to remove x entirely y can equal ”

A very handy method to keep in mind more so for data manipulation but at times can have uses for data output. This item will look for any character you define and replace it with whatever you specify. Common examples include manipulating dates.

For example the date may have been saved as ‘22/12/2014’ in order to use the date for a portfolio report or any comparison (eg comparing one date with another) you need to reduce it to the raw numbers.

  <:let mystring=’22/12/2014’:><:=str(mystring).replace(‘/’, ‘ ’):>

Slicing

Slicing syntax or literally slicing the string into its subparts (characters) can be useful for both data manipulation and data output.

As we mentioned at the start strings are made up of characters. So in the string ‘Gold Service’ we can see the characters of the string and also the position they occupy from the view of the system.

String G o l d   S e r v i c e
Position 0 1 2 3 4 5 6 7 8 9 10 11

 

  • You will notice that the first character takes the 0 position
  • And that space counts as a character

So slicing works by taking the specified start and end positions you want

<:=str(your_string)[start:end]:>

Note that the end point is the character where the slicing stops but doesn’t include the end character. The start character is always included and the end always excluded.

So for ‘Gold’ we would need [0:4] if we used [0:3] we would get ‘Gol’

Nnow that we know the positions of our string if we wanted to just extract the specific service standard we could use <:=str(myservice_benchmark)[0:4]:> and this would return ‘Gold’

Two of the most common times you may see slicing in action in Xmerge is for things like the first initial of a client name and or ABN output.

Example

My client’s title, first name and last name is: Mr Sample Client.

But on my correspondence I want to show: Mr S. Client

I would use the following syntax: <:=$client.title:> <:=str($client.first_name)[0:1]:>. <:=$client.last_name:>

ABN data is another one where it may not be formatted correctly in many cases it may be stored as a whole number (integer) or a string without the formatting. So our ABN might be: 90111222333 and we want to show it as 90 111 222 333

ABN 9 0 1 1 1 2 2 2 3 3 3
Position 0 1 2 3 4 5 6 7 8 9 10
  <:=str(myabn)[0:2]:> <:=str(myabn)[2:5]:> <:=str(myABN)[5:8]:> <:=str(myabn)[8:11]:>

 

It’s also worth noting that each position in our strings is a reference position or index. That means for single characters we don’t necessarily need to slice. Using our client first initial example, a more straight forward implementation we could use would be: <:=str($client.first_name)[0]:> and whilst unlikely (because its not automatically forced in Xplan) if we wanted to add some redundancy to ensure it always merges as a capital, we could do <:=str($client.first_name).upper()[0]:>

Other slicing bits

With my_string being equal to ‘Gold Service’

<:=str(my_string)[5:]:> Would return all characters after the first four. Gold Service would return ‘Service’
<=str(my_string)[-7:]:> Would exclude the last seven characters and return ‘Gold’
<:=str(my_string)[-3:]:> Returns ‘Service’

Conditioning and Operators

Method
.
What it does
.
Code example
.
len

Returns the length (len) of an object.

Short for length, it is used more than just with strings but you may see it often used around string and text items for conditioning. Unlike our positions or indexes, len counts the characters sequentially but does include white spaces so our ‘Gold Service’ string would return a len of 12

  <:=len($client.first_name):>
<:=len(my_string):>
<:if len(str(mystring).strip())>0:><:end:>
in

In is an operator that can be used to check if X exists (in) Y.

If x is found to exist in Y it returns a true value as the condition is met.

For example:

<:if ‘Balanced’ in str($client.risk_profile):><:end:> Checks to see if ‘Balanced’ is in the string that gets returned for the clients risk profile. If the clients right profile was ‘Balanced’ it will activate the condition, if the clients risk profile was ‘High Growth’ it would return false and the condition wouldn’t activate.

It’s important to be aware of the data you are trying to compare. This is true of all XMERGE but in the above example if our ‘Balanced’ risk profile was actually called “balanced” in lower case (in the system assumptions) it would return a false value, conversely if we used <:if ‘balanced’ in str($client.risk_profile):> and the actual client risk profile was ‘Balanaced’ the condition would fail.

So it’s important to always be comparing like data, for extra redundancy we might use:  <:if ‘balanced’ in str($client.risk_profile).lower():>

  <:if ‘X’ in str(y):><:if ‘Balanced’ in str($client.risk_profile):>

<:if str($client.risk_profile) in [‘Balanced’]:>

not in

Same as above but checks if X is not in Y

  <:if ‘Balanced’ not in str($client.risk_profile):>
+

+ or concatenate is a way of adding strings together. Generally this is useful for when you are working with variables. For example, lets say we wanted to represent the clients full name, traditionally you would do this via calling <:=$client.first_name:> <:=$client.last_name:> but if for some reason you absolutely had to show that in one bit of code you could concatenate or add the strings like this: <:=str($client.first_name)+’ ‘+str($client.last_name):>

In the above you can see we have added (+) both a space between the first and last name as well as adding the last name, all in the one code call. In general though you are likely to use this more with variables such as below: <:let clientFullName=str($client.first_name)+’ ‘+str($client.last_name):> Whenever we call <:=clientFullName:> the output would return ‘Sample Client’ More on variables later though.

  <:=str($client.first_name)+’ ‘+str($client.last_name):>

Conclusion

So hopefully you are now feeling excited…or looking forward..maybe just ready to tackle strings and getting the data and formatting you want in your xplan templates.

If you found this helpful or you have any follow up questions let us know below and stay tuned for future articles.

build a helpful, collaborative, innovative and beneficial community

For a long time now xplan development and coding has been the domain of mystics, those keepers of knowledge who magically make those templates and things in xplan work but who rarely explain the why and horde away knowledge like its some sort of lost treasure.

Simply put, you can’t build a helpful, collaborative, innovative and beneficial community for everyone, without those foundations of knowledge and access.

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 4 Comments
  1. was able to actually finish the small changes we wanted to make to some of our templates with this piece. Thank you will have to find time to read all the other posts now.

  2. Didn’t think googling help on xmerge would give me any luck but found this and using .replace() let me fix an issue in the SOA. Will share this around. Cheers, Daniel

Leave a Reply

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