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 of the three helpers takes three arguments, all of which are required:
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. UseZ
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]
- dateFormat (time is optional) —
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.Tip The Airship SDK gathers
ua_language
andua_country
attributes for your app audience. You can use these values to determine the locale for date and time formatting.format
— One ofFULL
,LONG
,MEDIUM
, orSHORT
, determining how to display the date-time value. Using our example of1983-01-31T12:36:35
from above, you can output the following formats (assumingen-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
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.{{$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!
Categories