Date and time helpers
Date and time helpers transform content in Handlebars expressions.
Format dates and times
You can format date and time values to fit your audience’s needs using dateFormat
, timeFormat
, and datetimeFormat
helpers.
For example, if you have a birthdate
attribute containing the value 1983-01-31T12:36:35
, you could reformat the string so that it makes more sense to your audience: {{dateFormat birthdate locale="en-US" format="SHORT"}}
would resolve to 01/31/1983
.
Each helper takes the arguments: datetime, locale, format, and pattern.
Datetime
An ISO 8601 string datetime — In general, we recommend that you use uniform datetime values since they work for all three helpers, but the actual datetime string requirements vary per helper.
[Offset]
is the time zone offset from UTC. Use Z
for UTC, or one of the following formats ±00:00
, ±0000
, ±00
. For example: -08:00
, -0800
, or -08
for PST.
Optional parts of a datetime string appear in brackets.
- dateFormat (time is optional) —
yyyy-MM-dd[[' ']['T']HH:mm[:ss[.SSS][Offset]]
- timeFormat (date is optional) —
[yyyy-MM-dd[' ']['T']]HH:mm[:ss[.SSS]][Offset]
- datetimeFormat —
yyyy-MM-dd[' ']['T']HH:mm[:ss[.SSS]][Offset]
Locale
locale
— The user’s 2-letter language and country codes, joined by a dash, e.g., en-US
. This localizes the date and time output for your audience. The language is an ISO 639 code. The country is an ISO 3166-1 alpha-2 code.
The Airship SDK gathers ua_language
and ua_country
attributes for your app audience. You can use these values to determine the locale for date and time formatting.
Format
format
— Optional. One of FULL
, LONG
, MEDIUM
, or SHORT
, determining how to display the date-time value. Cannot be used in combination with pattern
. Using our example of 1983-01-31T12:36:35
from above, you can output the following formats (assuming en-US
locale).
datetimeFormat
formats and example output:
FULL
— Tuesday, January 31, 1983 12:36:35 PM ZLONG
— January 31, 1983 12:36:35 PM ZMEDIUM
— Jan 31, 1983 12:36:35 PMSHORT
— 1/31/1983 12:36 PMNote FULL
andLONG
formats include time zone information. If you don’t set a time zone value in your datetime string, Airship assumesZ
(UTC/GMT).
dateFormat
formats and example output:
FULL
— Tuesday, January 31, 1983LONG
— January 31, 1983MEDIUM
— Jan 31, 1983SHORT
— 1/31/1983
timeFormat
formats and example output:
FULL
— 12:36:35 PM ZLONG
— 12:36:35 PM ZMEDIUM
— 12:36:35 PMSHORT
— 12:36 PM
Pattern
pattern
— Optional. A custom formatting pattern. Cannot be used in combination with format
. Only the parts that are relevant to the type of formatting are allowed, e.g., date parts are not allowed within timeFormat
. The most common specifiers appear in the table below.
Specifier | Output | Example |
---|---|---|
y | Year | yyyy for 2023 , yy for 23 |
M | Month | M for 4 , MMMM for April |
d | Day of Month | d for 5 , dd for 05 |
e | Day of Week | e for 2 , eeee for Wednesday |
a | AM/PM | a for PM |
h | Hour (1-12) | hh for 12 |
K | Hour (0-11) | KK for 11 |
k | Hour (1-24) | kk for 12 |
H | Hour (0-23) | HH for 11 |
m | Minute | mm for 30 |
s | Second | ss for 55 |
V | Time Zone ID | VV for America/Los_Angeles |
z | Time Zone Name | z for PDT |
O | Localized Zone Offset | O for GMT+8 |
X | Offset ‘Z’ for zero | X for Z , XXX for -07:00 |
Z | Offset | Z for -0700 |
These specifiers adhere to the following rules:
- When specifying numbers that may include a leading zero, a single character will omit the leading zero and double characters will include the leading zero. For example, for the fourth hour:
h
will output4
hh
will output04
- When specifying text output, 1–3 characters specify shortened forms, 4 characters specifies the full form, 5 characters specifies the narrow form. For example, for the month of April in
en-US
locale:M
will output4
MM
will output04
MMM
will outputApr
MMMM
will outputApril
MMMMM
will outputA
- Literal values may be specified in square brackets, e.g.,
['T']
will yieldT
.
Example uses of pattern
:
{{timeFormat "13:30:10" locale="en-US" pattern="h:mma"}}
yields1:30PM
{{datetimeFormat "2023-03-29T13:30:10" locale="en-US" pattern="yyyy-MM-dd['T']HH:mm:ss"}}
yields2023-03-29T13:30:10
{{dateFormat "2023-03-29T13:30:10" locale="en-US" pattern="MMM d, yyyy"}}
yieldsMar 29, 2023
{{dateFormat "2023-03-29T13:30:10" locale="de-DE" pattern="d MMMM yyyy"}}
yields29 März 2023
Additional formatting options are available and follow the Java DateTimeFormatter
rules .
Determine today/yesterday/tomorrow
Determine whether a given date is today, yesterday, or tomorrow. This helper is used within an evaluation only. It does not return a displayed result.
$isToday <date>
— Determines whether the given date is today, relative to the current time in UTC.$isTomorrow <date>
— Determines whether the given date is tomorrow, relative to the current time in UTC.$isYesterday <date>
— Determines whether the given date is yesterday, relative to the current time in UTC.
These helpers can be combined with conditional operators to return true or false in a helper block, or with a preceding #
and a closing /
to create its own block.
{{#if ($isToday birthdate)}}
Happy birthday, {{name}}
{{/if}}
{{#$isToday birthdate}}
Happy birthday, {{name}}
{{/$isToday}}
Get date and time
Return the current date or date and time.
$now
— Returns a datetimeFormat (yyyy-MM-ddTHH:mm:ssZ
) representing the current instant at UTC.$today
— Returns a dateFormat (yyyy-MM-dd
) representing today.
Purchase Date: {{$today}}
// Using `timeFormat` to remove the date to get only the time:
Your order has been received at {{timeFormat ($now) format="SHORT"}}
Calculate date and time
Return a future date, time between dates, or age.
{{$addTo <date> <amount> timeUnit="<time unit>"}}
— Returns a future date by adding an amount of time in days, weeks, months, or years to a given date in a dateFormat or datetimeFormat.{{ <format> ($addTo (<date>) <amount> timeUnit="<time unit>") locale="<locale>" pattern="<pattern>"}}
— Returns a future date in your preferred format and pattern by adding an amount of time in days, weeks, months, or years to a given date. For example:{{dateFormat ($addTo ($today) 7 timeUnit="days") locale="en-US" pattern="dd-MM-yy"}}
.{{$daysBetween <date1> <date2>}}
— Returns the number of days between two dates.{{$weekBetween <date1> <date2>}}
— Returns the number of weeks between two dates.{{$timeBetween <date1> <date2> timeUnit="<time unit>"}}
— Returns the number of time units between two dates in days, weeks, months, or years.{{$age}}
— Returns an age as of today for a given date. For example:{{$age "1970-06-01"}}
.
The timeUnit="<time unit>"
in the $addTo
and $timeBetween
helpers is optional. If not specified it will default to days
. Time units are not case-sensitive.
Your membership expires in 3 days, on {{$addTo "2020-02-27T12:30Z" 3 timeUnit="days"}}
The <date>
input in $daysBetween
, $weekBetween
, and $timeBetween
must be in a dateFormat or datetimeFormat. If the second date is before the first date the result will be a negative number. The calculation returns a whole number, representing the number of complete time units between the two dates. For example, if the time unit is days
and there are 30 hours between the two dates, then the result will be 1 day.
There are {{$daysBetween ($today) "2021-12-25"}} left until Christmas!
There are {{$timeBetween ($today) springSaleEnds timeUnit="days"}} days left in our Spring Sale!
Transform a date to another time zone
You may take a given date and transform it to another time zone. This can be used when paired with formatted output to give a more localized time:
{{$toTimezone <date> <timezone_id>}}
timezone_id
is expected to be the text identifier for the timezone, e.g., America/Los_Angeles
.
{{datetimeFormat ($toTimezone "2023-04-05T15:24:40Z" "America/Los_Angeles") locale="en-US" format="LONG"}}
Categories