Formatting

When displaying values of entities stored in Bot Memory, y ou can use Handlebars templates for some common formatting needs.

Displaying Entity Values

Each entity value stored in the short-term memory can be accessed by it’s name:

{{entityName}}

For example:

{{doctor}} is not available on {{date}}.

Will be displayed as: “Dr. John Burke is not available on 11 Feb.”

Formatting

It’s often that the entities that will be stored in a conversation might have properties that need to be formatted. For example, invoking an entity that has a date property will be displayed as a raw string Fri Aug 12 1987 00:00:00 GMT-0700 (Pacific Daylight Time) instead of a simple format such as August 12, 1987.

{{birthday}} <!-- output: Fri Aug 12 1987 00:00:00 GMT-0700 (Pacific Daylight Time) -->

To make it easy to format values in the memory, you have a set of built-in formatters that will save you time display the data in the format you want.

{{$date birthday}} <!-- output: Aug 12, 1987 -->

All formatters are prefixed with $ except for the block formatters like #forEach which are prefixed with # and have a closing tag. Block formatters wrap a part of the template to use it in a custom way.

    base template {{#blockFormatter}}child template{{/blockFormatter}}

Here is a list of the built-in formatters that you can directly use with every expression statement.

Date

You can format a date with either a shortcut built-in $date formatters that we have listed below, or use a custom formatting string.

     {{$date birthday}}               <!-- output is 'Jun 15, 2015' -->
     {{$date birthday 'medium'}}      <!-- output is 'Jun 15, 2015, 9:43:11 PM' -->
     {{$date birthday 'shortTime'}}   <!-- output is '9:43 PM' -->
     {{$date birthday 'mm:ss'}}       <!-- output is '43:11' -->

In case you have separate entities for date and time, which are of types Date and Time respectively, you can format them the following way. Note that the format parameter at the end cannot be omitted in this case.

    <!-- output is 'Jun 15, 2015, 9:43:11 PM' -->
    {{$date date time 'medium'}}
  • 'medium' - equivalent to 'll[,] LTS' (e.g. Sep 3, 2010, 12:05:08 PM for en-US)
  • 'short' - equivalent to 'L[,] LT' (e.g. 9/3/2010, 12:05 PM for en-US)
  • 'fullDate' - equivalent to 'dddd[,] LL' (e.g. Friday, September 3, 2010 for en-US)
  • 'longDate' - equivalent to 'LL' (e.g. September 3, 2010 for en-US)
  • 'mediumDate' - equivalent to 'll' (e.g. Sep 3, 2010 for en-US)
  • 'shortDate' - equivalent to 'L' (e.g. 9/3/2010 for en-US)
  • 'mediumTime' - equivalent to 'LTS' (e.g. 12:05:08 PM for en-US)
  • 'shortTime' - equivalent to 'LT' (e.g. 12:05 PM for en-US)
  • 'fromNow' - relative time from now formatted as literal expression. Dates in the past will be shown as 3 minutes ago, 11 hours ago, 5 years ago and dates in the future will be shown as in 4 minutes, in 1 hour, in 2 days etc.
Token Output
Month M 1 2 ... 11 12
Mo 1st 2nd ... 11th 12th
MM 01 02 ... 11 12
MMM Jan Feb ... Nov Dec
MMMM January February ... November December
Quarter Q 1 2 3 4
Qo 1st 2nd 3rd 4th
Day of Month D 1 2 ... 30 31
Do 1st 2nd ... 30th 31st
DD 01 02 ... 30 31
Day of Year DDD 1 2 ... 364 365
DDDo 1st 2nd ... 364th 365th
DDDD 001 002 ... 364 365
Day of Week d 0 1 ... 5 6
do 0th 1st ... 5th 6th
dd Su Mo ... Fr Sa
ddd Sun Mon ... Fri Sat
dddd Sunday Monday ... Friday Saturday
Day of Week (Locale) e 0 1 ... 5 6
Day of Week (ISO) E 1 2 ... 6 7
Week of Year w 1 2 ... 52 53
wo 1st 2nd ... 52nd 53rd
ww 01 02 ... 52 53
Week of Year (ISO) W 1 2 ... 52 53
Wo 1st 2nd ... 52nd 53rd
WW 01 02 ... 52 53
Year YY 70 71 ... 29 30
YYYY 1970 1971 ... 2029 2030
Y 1970 1971 ... 9999 +10000 +10001
Note: This complies with the ISO 8601 standard for dates past the year 9999
Week Year gg 70 71 ... 29 30
gggg 1970 1971 ... 2029 2030
Week Year (ISO) GG 70 71 ... 29 30
GGGG 1970 1971 ... 2029 2030
AM/PM A AM PM
a am pm
Hour H 0 1 ... 22 23
HH 00 01 ... 22 23
h 1 2 ... 11 12
hh 01 02 ... 11 12
k 1 2 ... 23 24
kk 01 02 ... 23 24
Minute m 0 1 ... 58 59
mm 00 01 ... 58 59
Second s 0 1 ... 58 59
ss 00 01 ... 58 59
Fractional Second S 0 1 ... 8 9
SS 00 01 ... 98 99
SSS 000 001 ... 998 999
SSSS ... SSSSSSSSS 000[0..] 001[0..] ... 998[0..] 999[0..]
Time Zone z or zz EST CST ... MST PST
Z -07:00 -06:00 ... +06:00 +07:00
ZZ -0700 -0600 ... +0600 +0700
Unix Timestamp X 1360013296
Unix Millisecond Timestamp x 1360013296123
Time LT 8:30 PM
Time with seconds LTS 8:30:25 PM
Month numeral, day of month, year L 09/04/1986
l 9/4/1986
Month name, day of month, year LL September 4 1986
ll Sep 4 1986
Month name, day of month, year, time LLL September 4 1986 8:30 PM
lll Sep 4 1986 8:30 PM
Month name, day of month, day of week, year, time LLLL Thursday, September 4 1986 8:30 PM
llll Thu, Sep 4 1986 8:30 PM

Kinvey Chat is using moment.js to format the dates. You can see the full explanation of the formatting strings here.

Dates and timezones

Dates are formatted using the bot’s or user’s timezone. For the examples, assume that the timezone is ‘America/New_York (GMT-05:00)’ and the format is ‘YYYY-MM-DD HH:mm ZZ’.

If the date contains timezone then it’s converted to the bot’s/user’s timezone.

Date Formatted date
2017-10-12T15:30:00Z 2017-10-12 10:30 -0500
2017-10-12T00:00:00Z 2017-10-11 19:00 -0500
2017-10-12T00:00:00+02:00 2017-10-11 17:00 -0500

If the date has no timezone then the bot’s/user’s timezone is set for the date, but it’s not converted.

Date Formatted date
2017-10-12 2017-10-12 00:00 -0500
2017-10-12 15:30 2017-10-12 15:30 -0500

In case you still need to convert the date in a specific time zone you can use an additional parameter:

    <!-- date = '2017-10-12', time = '15:30', timezone = 'America/New_York' -->
    {{$date date time 'medium' 'UTC'}} <!-- output is 'Dec 10, 2017, 20:30:00 PM' -->

Currency

You can format a number as currency by using the $currency formatter in every expression statement by passing an ISO 4217 currency code such as 'USD'. You can also control the number of digits and the usage of symbol ($) or currency code (USD) as a suffix of the value.

     {{amount}}                             <!-- 2230.30 -->
     {{$currency amount 'USD'}}             <!-- $2,230.30 -->
     {{$currency amount 'USD' precision=0}} <!-- $2,230 -->

Here is the full set of parameters that you can use when formatting currency:

  • locale - a culture-specific locale e.g. 'en-US'
  • precision - number of decimal digits e.g. 2

Percent

You can format a number as percent by using the $percent formatter. You also have the option to pass the number of decimal digits as an integer.

     {{amount}}            <!-- 0.3245 -->
     {{$percent amount}}   <!-- 32.45% -->
     {{$percent amount 4}} <!-- 32.4500% -->

Number

You can format a number as text by configuring locale, precision, decimal and thousand separators.

     {{amount}}                                   <!-- 2230.30 -->
     {{$number amount precision=0}}               <!-- 2230 -->
     {{$number amount precision=0 thousand=','}}  <!-- 2,230 -->

Here is the full set of parameters that you can use when formatting a number:

  • locale - a culture-specific locale e.g. 'en-US'
  • decimal - a decimal separator '.'
  • thousand - a thousand separator - ','
  • precision - number of decimal digits e.g. 2

UpperCase

You can format a string to upper case using the $uppercase formatter.

     {{title}}             <!-- 'This is my title' -->
     {{$uppercase title}}  <!-- 'THIS IS MY TITLE' -->

LowerCase

You can format a string to lower case using the $lowercase formatter.

     {{title}}             <!-- 'This is my title' -->
     {{$lowercase title}}  <!-- 'this is my title' -->

Capitalize

You can capitalize the first word of a sentence using the $capitalize formatter.

     {{title}}              <!-- 'this is my title' -->
     {{$capitalize title}}  <!-- 'This is my title' -->

CapitalizeAll

You can capitalize all words of a sentence using the $capitalizeAll formatter.

     {{title}}                 <!-- 'this is my title' -->
     {{$capitalizeAll title}}  <!-- 'This Is My Title' -->

EncodeURI

You can encode a string as a URI component to use in a URI using the $encodeURI formatter.

    {{search}}                                  <!-- 'The Great Gatsby' -->
    https://book.shop/?q={{$encodeURI search}}  <!-- 'https://book.shop/?q=The%20Great%20Gatsby' -->

JSON

You can serialize an object as JSON string using the $json formatter.

    {{location}}        <!-- '[object Object]' -->
     {{$json location}}  <!-- '{"latitude":42.650615,"longitude":23.379194}'

forEach

You can iterate over each item in an array using the for #forEach block formatter.

    <!-- '["John", "Maria", "Robert", "Anna"]' -->
    {{$json friends}}

    <!-- 'Hello, John! Hello, Maria! Hello, Robert! Hello, Anna! ' -->
    {{#forEach friends}}Hello, {{item}}! {{/forEach}}

concat

Use $concat formatter to concatenate multiple values as a string.

    <!-- 'Date: 2017.10.10 Time: 10:00' -->
    {{$concat 'Date: ' date ' Time: ' time}}