Skip to content

BLL Date

Arie J. Godschalk edited this page Nov 15, 2026 · 4 revisions

date: format dates and clock times

Method reference · time · number · Examples

date formats a calendar date or clock time. It returns text, using the configured BLL locale and Homey's time zone unless the caller or expression supplies overrides. In a supported text field:

Today is {[ date("dddd") ]}.

In an expression-only card, enter date("dddd") without {[ ]}.

Arguments

date(format)
date(format, dateValue, locale, timeZone)
date(format, locale, timeZone)

The last form uses the current date and a recognized locale tag, for example date("dddd", "nl", "Europe/Amsterdam"). The second form accepts a date string with an offset, a Date, or a Unix timestamp in milliseconds. Pass null as dateValue when you want the current time with explicit locale and time zone in the four-argument form. Use an IANA time-zone name such as Europe/Amsterdam or UTC.

For reliable results, prefer ISO 8601 strings with Z or an explicit offset. Ambiguous local date strings can be interpreted differently. In the 4.2.3 source, a numeric zero date is treated as absent; do not rely on date(..., 0) to format the Unix epoch. Explicit overrides and custom formats can also interact; preview the result in your installed version.

Format codes

The format argument accepts the built-in names and tokens below. Codes are case-sensitive; the differently-cased aliases listed here are separate supported codes. Locale and time zone can change the resulting text. Unless noted, the example outputs use locale en-US, the instant 2026-11-12T13:08:09.123Z and time zone Europe/Amsterdam.

Named date, time and date-time formats

These names select locale-aware Intl styles. Both the codes listed in App settings → Formats and the aliases shown here are accepted. Results show the built-in formats before any settings override.

Output Style Accepted format codes Example result (en-US)
Date and time Full DATETIMELONG, datetimelong, LONGDATETIME, longdatetime Thursday, November 12, 2026 at 2:08:09 PM Central European Standard Time
Date and time Long DATETIME November 12, 2026 at 2:08:09 PM GMT+1
Date and time Medium datetime Nov 12, 2026, 2:08:09 PM
Date and time Short datetimeshort, shortdatetime 11/12/26, 2:08 PM
Date Full DATELONG, datelong, LONGDATE, longdate Thursday, November 12, 2026
Date Long DATE November 12, 2026
Date Medium date Nov 12, 2026
Date Short dateshort, shortdate 11/12/26
Time Full TIMELONG, timelong, LONGTIME, longtime 2:08:09 PM Central European Standard Time
Time Long TIME 2:08:09 PM GMT+1
Time Medium time 2:08:09 PM
Time Short timeshort, shorttime 2:08 PM

Date and clock-time tokens

Use the longer tokens where one token starts with another, such as MMMM before MM or HH24 before HH.

Tokens Meaning Example result (en-US)
yyyy, yy Four-digit or two-digit year 2026, 26
MMMM, MMM, MM, M Full month name, abbreviated month name, two-digit month, numeric month November, Nov, 11, 11
dddd, ddd Full or abbreviated weekday name Thursday, Thu
dd, d Two-digit or numeric day of month 12, 12
HH, H 24-hour clock, with leading zero or without 14, 14
HH24, H24 24-hour-cycle clock using the 1–24 cycle (midnight can be 24) 14, 14
hh, h 12-hour clock, with leading zero or without 02, 2
tt Locale-specific AM/PM marker PM
mm, m Two-digit or numeric minute 08, 8
ss, s Two-digit or numeric second 09, 9
fff, ff, f Millisecond fraction with three, two or one digits 123, 12, 1

Additional date/time tokens

Tokens Meaning Example result (en-US)
PERIOD, period Locale-specific day-period text, in long or short form (for example, morning or afternoon) in the afternoon
ERA, era Locale-specific era name, in long or short form Anno Domini, AD
KK, kk Long or short localized time-zone name Central European Standard Time, GMT+1
z, zz Numeric time-zone offset, with one- or two-character hour width +1, +01
Z, ZZ Numeric time-zone offset prefixed with GMT, with one- or two-character hour width GMT+1, GMT+01
ISO UTC ISO timestamp 2026-11-12T13:08:09.123Z
ISOZ ISO-like date and time with the configured time-zone offset 2026-11-12T14:08:09.123+01:00

PERIOD and period are distinct from tt: the former return a localized day-period phrase, while tt returns the locale's AM/PM marker. Day-period and era text depend on locale and date. The numeric z, zz, Z and ZZ forms are legacy offset formats; check their output in the settings preview, especially for time zones whose offsets include minutes. In the 4.2.3 implementation, ERA removes the host's current UTC year from the formatted result; the Anno Domini example assumes the host year is 2026. A different year may remain in the output.

For example, these expressions return the current localized day period in long and short styles:

{[ date("PERIOD") ]}
{[ date("period") ]}

Literal text and customized formats

Text inside double quotes is copied literally into the result. For example:

{[ date('yyyy-MM-dd "at" HH:mm') ]}

Use "" inside a format to output a literal double quote. In App settings → Formats, you can change built-in formats or add a named custom format, then use that name as the date format argument. Preview custom formats before using them; changing a built-in format can affect other apps that use it.

Community screenshots

The following code-reference images are from the BLL users topic, post 3. They show examples for the locale used at the time and may differ from your app version and settings. Some codes in the historical screenshots have changed; use the current code table above rather than assuming the screenshots match your installed version.

BLL date and time format examples, part one

Historical format-reference screenshot, part one; use the current table above for supported tokens and examples.

BLL date and time format examples, part two

Historical format-reference screenshot, part two; labels and defaults may differ from the current app.

BLL date and time format examples, part three

Historical format-reference screenshot, part three; verify any code against the current reference above.

Examples with a fixed date

Each row is a bare expression for an expression card. Wrap it in {[ ... ]} to use it inside supported text. Unless otherwise stated, the fixed input below is 12 November 2026 at 13:08:09.123 UTC.

Expression Example output
date("yyyy-MM-dd", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") 2026-11-12
date("dd/MM/yyyy", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") 12/11/2026
date("dddd, d MMMM yyyy", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") Thursday, 12 November 2026
date("HH:mm:ss", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") 13:08:09
date("hh:mm tt", "2026-11-12T13:08:09.123Z", "en-US", "UTC") 01:08 PM
date("HH:mm", "2026-11-12T13:08:09.123Z", "en-GB", "Europe/Amsterdam") 14:08
date("HH:mm", "2026-11-12T13:08:09.123Z", "en-GB", "America/New_York") 08:08
date("ISO", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") 2026-11-12T13:08:09.123Z

The same instant can have a different date in another time zone. Date and language conventions may also change across Homey/runtime versions.

Current time and timestamps

Supported text What it produces
The time is {[ date("HH:mm") ]} Current local clock time.
Tomorrow at this instant: {[ date("yyyy-MM-dd HH:mm", now + 86400000) ]} The instant 24 hours from now.
In 90 minutes: {[ date("shorttime", now + 90 * 60000) ]} Clock time 90 minutes from now.
Timestamp: {[ now ]} Current Unix time in milliseconds.
Seconds: {[ Math.floor(now / 1000) ]} Current Unix time in seconds.

now is set once per expression evaluation. A period of 24 hours is not always the next local calendar day across daylight-saving transitions.

Named and custom formats

In App settings → Formats, add a custom name such as ReportDate and set its definition to yyyy-MM-dd. Save it, then use {[ date("ReportDate") ]}. The settings page previews the output. Existing default formats can also be changed, affecting other apps using BLL date formats. Choose unique names and test before changing shared definitions.

Literal text in a format can be enclosed in double quotes, for example:

{[ date('yyyy-MM-dd "at" HH:mm') ]}

The quotes around at are part of the format; the outer single quotes are JavaScript string delimiters.

Clone this wiki locally