How to format dates in your XPLAN templates with XMERGE
20 March 2018 by PlanFocus Team

The Xmerge coding library provides useful functions to manipulate dates. We use it a lot when working with our clients, and we’d like to share some useful operations that might be useful to you as well.

In this article, you will understand how date formatting in XMerge works and learn how to choose between different available character codes to correctly display a date attribute in your document. By using some of these techniques, you can make your documents look attractive and unique to clients. Having a consistency of approach can also make supporting your documents a lot easier for your support team. This all leads to happier clients and more professional looking documents.

 

1. Datetime_merge: current Date and Time of when your document is generated

With XMerge you can quickly insert the current date (and time) into the body of a document as well as into the header and footer. If you want the date to automatically update when you merge your document template you need to use the datetime_merge object into your template; this will help eliminate the tedious chore of manually deleting prior dates every time you merge your document.

The basic Xmerge syntax to print the date and time object is as follows:

<:=datetime_merge:>

Sample output:

04/02/2018 10:31:23 am

However, if you want to display the date without the time or to display the date in a different format, for example (“4 Feb 2018” instead of “04/02/2018”), Xmerge also provides a variety of pre-defined formats. In the next section we’ll show you how to use and combine them to suit any business communications objective.

 

2. Format: create the date format that suits your business communications

The datetime_merge object provides a convenient method called format to handle the date formatting. Using it allows you to create a string representing the date and time. This is done by using various codes that let you control how the date looks after conversion.

Here are a few common examples of character strings and their equivalent outputs (available from the IRESS template library):

Date Type Xmerge Syntax Example Output
Full date <:=datetime_merge.format(“full”):> Friday, 22 August 2014 at 10:34:57 am Australian Eastern Daylight Time
Full date without time <:=datetime_merge.format(“full”, True):> Friday, 22 August 2014
Medium date without time <:=datetime_merge.format(“medium”, True):> 03/08/2014
Short date <:=datetime_merge.format(“short”):> 3/08/14 10:34 am
Short date without time <:=datetime_merge.format(“short”, True):> 3/08/14
Day of the month as decimal number without leading zero <:=datetime_merge.format(“d”):> 3
Day of the month as a zero-padded number <:=datetime_merge.format(“dd”):> 03
Short month <:=datetime_merge.format(“MMM”):> Aug.
Full month <:=datetime_merge.format(“MMMM”):> August
Date without leading zero <:=datetime_merge.format(“d MMMM yyyy”):> 3 August 2014

 

While the table above shows common examples of pre-defined character strings that were built by IRESS, the table below shows the individual Character Codes that you can use to create your own date format string.

Date Type Code Xmerge Syntax Example Output
Weekday as abbreviated name. %a <:=datetime_merge.format(‘%a’):> Mon
Weekday as full name. %A <:=datetime_merge.format(‘%A’):> Monday
Day of the month as a zero-padded decimal number %d <:=datetime_merge.format(‘%d’):> 03
Month as abbreviated name %b <:=datetime_merge.format(‘%b’):> Sep
Month as full name %B <:=datetime_merge.format(‘%B’):> September
Month as a zero-padded decimal number. %m <:=datetime_merge.format(‘%m’):> 09
Year without century as a zero-padded decimal number %y <:=datetime_merge.format(‘%y’):> 13
Year with century as a decimal number. %Y <:=datetime_merge.format(‘%Y’):> 2013
Hour (24-hour clock) as a zero-padded decimal number. %H <:=datetime_merge.format(‘%H’):> 07
Hour (12-hour clock) as a zero-padded decimal number. %I <:=datetime_merge.format(‘%I’):> 07
Locale’s equivalent of either AM or PM. %p <:=datetime_merge.format(‘%p’):> AM
Minute as a zero-padded decimal number. %M <:=datetime_merge.format(‘%M’):> 06
Second as a zero-padded decimal number. %S <:=datetime_merge.format(‘%S’):> 05

 

Those character codes can also be put together to form a character string. Below is an example of how to combine them to suit your needs:

Date Type Xmerge Syntax Example Output
Date <:=datetime_merge.format(‘%d %B %Y’):> 03 August 2014
Date without leading <:=datetime_merge.format(‘%d %B %Y’).lstrip(‘0’):> 3 August 2014

 

The great part is that the format method can be used with any Date field (standard and custom fields), not just with the datetime_merge object.

Here is a list of Date fields that you may be using in your documents you may wish to apply some formatting to:

  • SoA Date
  • Meeting date
  • FSG version Date
  • Date of FSG provided
  • Date of Birth
  • Date of Will

Let’s look into an example. Suppose you have created a custom field called “Date of SOA” that displays on the cover page of your Statement of Advice document. By default if no formatting is applied the date of SOA displays in its short form e.g 03/08/2017.

Xmerge Syntax Example Output
<:=$client.date_of_soa:> 10/03/2018

 

Now if you wanted to change the format you would simply apply the format function to the Date field as previously described. This allows to control the formatting with an explicit format string as follows:

Xmerge Syntax Example Output
<:=$client.date_of_soa.format(‘%d %B %Y’):> 10 March 2018

 

Summary

  • Use datetime_merge object to pull through the current date and time of when the document is generated.
  • In conjunction to the above use the format function to provides a way to express the date and time in a variety of formats effectively.
  • You can choose between pre-built date time format or define your own character string format that suit your style

 

At PlanFocus, we create unique hand-crafted XPLAN sites that deliver your advice brand and use XPLAN to its full potential.  If you would like help with formatting dates with XMERGE or want to learn more about our services, please get in touch.

 

logo
1300 361 973

Latest Blog

©2022 PlanFocus, All Rights Reserved
Privacy PolicyTerms of Service