Date and time helpers

Formatting dates and times

You can format dates and times using helpers dateFormat, timeFormat, and datetimeformat. Each helper takes the arguments date-time, locale, format, and pattern.

Following the helper, you must include a date-time and locale. For example, {{dateFormat "1983-01-31T12:36:35" locale="en-US"}}. The format and pattern arguments are optional.

Examples of each helper:

You can also provide date-times using Date AttributesMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience. instead of a date-time string. When using Attributes, do not enclose them in quotes.

These examples show how the locale, format, and pattern arguments can transform a date-time, using a Date AttributeMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience. birthdate with value January 31, 1983, for the date-time:

Date-time

An ISO 8601 -formatted string — Required. In general, we recommend that you use uniform date-time values since they work for all three helpers, but the actual date-time string requirements vary per helper.

You can add [Offset] to specify 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.

Date-time format per helper, with optional parts of the string in brackets:

Locale

locale — Required. Date and time helper argument that renders the date and time according to the user’s 2-letter language and country codes, joined by a dash. Format example: locale="en-US". The language is an ISO 639  code. The country is an ISO 3166-1 alpha-2  code.

Locale values can also be provided using Date AttributesMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience. instead of an actual date-time string.

Format

format — Optional. Date and time helper argument that determines how to display the date-time value. One of FULL, LONG, MEDIUM, or SHORT. Format example: format="SHORT". FULL and LONG formats include time zone information. If you don’t set a time zone value in your date-time string, Airship assumes Z (UTC/GMT). format cannot be used in combination with pattern.

The following tables show examples and output of format for each date and time helper.

dateFormat examples:

timeFormat examples:

datetimeFormat examples:

Pattern

pattern — Optional. Date and time helper argument that specifies a custom formatting pattern. Format example: pattern="MMM d, yyyy". Only the parts that are relevant to the type of formatting are allowed. For example, date parts are not allowed within timeFormat. Cannot be used in combination with format.

The most common pattern specifiers:

The above specifiers adhere to the following rules:

1. 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
2. When specifying text output, 1 to 3 characters specify shortened forms, four characters specifies the full form, five characters specifies the narrow form. For example, for the month of April with en-US locale:
   • M will output 4
   • MM will output 04
   • MMM will output Apr
   • MMMM will output April
   • MMMMM will output A
3. Literal values may be specified in square brackets. For example, ['T'] will yield T.

Additional formatting options are available and follow the Java DateTimeFormatter rules .

Example use and output of pattern for each date and time helper:

Determining today, yesterday, or tomorrow

Return true or false based on whether a given date is today, yesterday, or tomorrow relative to the current time in UTC:

• {{$isToday "<date>"}}
• {{$isYesterday "<date>"}}
• {{$isTomorrow "<date>"}}

Dates must be formatted as yyyy-mm-dd or as a date-time. These helpers are generally used within an evaluation only rather than displaying the result.

You can combine them with conditional operators to return true or false in a helper block. You can also use them with a preceding # and a closing / to create a separate block:

{{#if ($isToday birthdate)}}
Happy birthday, {{name}}
{{/if}}

{{#$isToday birthdate}}
Happy birthday, {{name}}
{{/$isToday}}

Getting date and time

Return the current date, or date and time, in UTC:

• {{$now}} — Returns the current date and time in UTC in datetimeFormat (yyyy-MM-ddTHH:mm:ssZ).
• {{$today}} — Returns the current date in dateFormat (yyyy-MM-dd).

Example use in a purchase order:

Purchase Date: {{$today}}

// Using `timeFormat` to remove the date to get only the time:
Your order was received at {{timeFormat ($now) format="SHORT" locale="en-US"}}.

Calculating date and time

Return an age, future date, or time between dates:

Dates must be formatted as yyyy-mm-dd or as a date-time.

The following examples assume today’s date is March 25, 2024, and some also use the $today and pattern helpers:

For $daysBetween, $weekBetween, and $timeBetween:

• If the second date is earlier than 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 output will be “1”.

Example usage in messages:

Transforming a date to another time zone

Transform a date to another time zone using {{$toTimezone "<date>" "<timezone_id>"}}.

Dates must be formatted as yyyy-mm-dd or as a date-time. The timezone_id is the text identifier for the time zone. For example, America/Los_Angeles. See the TZ column  in the list of Time Zone abbreviations.

The first example in each pair uses standard formatting, and the second adds the datetimeFormat helper and format argument to give a more localized time: