Handlebars Helper Function: format

Formats output based on a format string and optional type specification. It supports formatting dates, numbers, and strings according to specified patterns and culture settings.

Availability

This helper is available in the Winter ’26 release of Marketing Cloud Next.

Syntax

{{format subject formatString type culture}}

Parameters

Format Strings

The value that you specify for the formatString parameter determines the type of formatting to apply to the subject. These sections describe the different format strings that you can use.

Date Format Strings

Date formats are highly configurable and can be customized to suit your needs. These sections describe the different format strings that you can use.

Preformatted Date and Time Strings

Use the string patterns listed in this table to format dates and times. The values in the Example Output column are based on the date Monday, March 15, 2024 at 2:30:45 PM in the UTC-6 time zone with the en_US culture.

Date Components

Use the string patterns listed in this table to format dates. The values in the Example column are based on the date Monday, March 15, 2024 at 2:30:45 PM in the UTC-6 time zone with the en_US culture.

Time Components

Use the string patterns listed in this table to format times. The values in the Example column are based on the time 2:30:45 PM in the UTC-6 time zone with the en_US culture.

Date Literals and Separators

You can further format dates and times using these literals and separators.

Numeric Format Strings

You can customize the way that numbers are formatted by using predefined or custom format strings.

Predefined Numeric Format Strings

Use the string patterns listed in this table to format numbers. The values in the Example columns are based on the en_US culture setting.

Custom Numeric Format Strings

When you specify a custom numeric format string, use either # or 0 as a placeholder for the digits in the number.

Use the custom format strings listed in this table to format numbers. The values in the Example columns are based on the en_US culture setting.

To specify separate formats for positive, negative, and zero values, use the ; character. For example, {{format 1234.567, "N2;N0;N2"}} returns 1,234.57, and {{format -1234.567, "N2;(F2);N0"}} returns (1,234.57).

This table includes examples of custom numeric formatting strings.

String Formatting

When the type parameter is omitted or is set to string, these rules apply:

• If the formatString parameter is empty, the string is returned as-is.
• If any format string value is provided, the value is treated as a string template placeholder.
• If formatting fails, an exception is thrown.

These rules are applied when formatting strings:

1. All format patterns are case-sensitive.
2. Literal text must be enclosed in single or double quotes.
3. Use a backslash (\) to escape special characters.
4. If a pattern isn’t valid, an exception is thrown.
5. Date patterns work only with date types, and numeric patterns workonly with numbers.
6. Some patterns, such as day and month names, vary by culture.
7. Numbers can have up to 15 significant digits.
8. Use semicolon (;) to separate positive, negative, and zero formats.

Culture and Locale Specification

Use the culture parameter to specify the culture to use for formatting. These locale codes are supported:

• en-US (English - United States)
• en-GB (English - United Kingdom)
• fr-FR (French - France)
• de-DE (German - Germany)
• es-ES (Spanish - Spain)
• ja-JP (Japanese - Japan)
• zh-CN (Chinese - China)
• zh-TW (Chinese - Taiwan)

The culture value determines the date format conventions, currency symbols, decimal separators, thousands separators, day names, and month names that are used for formatting.

Return Value

The function returns the formatted value as a string. If formatting fails, it returns the original value as a string (backward compatibility). All format strings are case-sensitive.

See Also

• FormatCurrency
• FormatNumber