Date and time helpers

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.

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 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

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.

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 output 4
  • hh will output 04
• 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 output 4
  • MM will output 04
  • MMM will output Apr
  • MMMM will output April
  • MMMMM will output A
• Literal values may be specified in square brackets, e.g., ['T'] will yield T.

Example uses of pattern:

• {{timeFormat "13:30:10" locale="en-US" pattern="h:mma"}} yields 1:30PM
• {{datetimeFormat "2023-03-29T13:30:10" locale="en-US" pattern="yyyy-MM-dd['T']HH:mm:ss"}} yields 2023-03-29T13:30:10
• {{dateFormat "2023-03-29T13:30:10" locale="en-US" pattern="MMM d, yyyy"}} yields Mar 29, 2023
• {{dateFormat "2023-03-29T13:30:10" locale="de-DE" pattern="d MMMM yyyy"}} yields 29 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"}}