1. Home
  2. /Guides
  3. /Messaging
  4. /User guide
  5. /Personalization
  6. /Handlebars Reference
  7. /Date and time helpers

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:

  1. 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]

  2. 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 and ua_country attributes for your app audience. You can use these values to determine the locale for date and time formatting.

  3. format — One of FULL, LONG, MEDIUM, or SHORT, determining how to display the date-time value. 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 Z
    • LONG — January 31, 1983 12:36:35 PM Z
    • MEDIUM — Jan 31, 1983 12:36:35 PM
    • SHORT — 1/31/1983 12:36 PM
       Note

      FULL and LONG formats include time zone information. If you don’t set a time zone value in your datetime string, Airship assumes Z (UTC/GMT).

    dateFormat formats and example output:

    • FULL — Tuesday, January 31, 1983
    • LONG — January 31, 1983
    • MEDIUM — Jan 31, 1983
    • SHORT — 1/31/1983

    timeFormat formats and example output:

    • FULL — 12:36:35 PM Z
    • LONG — 12:36:35 PM Z
    • MEDIUM — 12:36:35 PM
    • SHORT — 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!