On this page

Date and Time Formatting

LiveWhale uses PHP’s date formatting functions. You can use the following date formatting characters below to build date format strings to use in LiveWhale widgets. See the formatting options with examples below:

Date Variables

Variable Description Values
%d Day of month, with leading zeros 01-31
%j Day of month, without leading zero 1-31
%S The English suffix for the day of the month st, nd, or th in the 1st, 2nd, or 15th
%I Day of week, full name (lowercase ‘L’) Sunday – Saturday
%D Day of week, three letter name Mon – Sun
%m Month, numeric, with leading zeros 01–12
%n Month, numeric, without leading zeros 1–12
%F Month, full text January – December
%M Month, three letter name Jan – Dec
%Y Year, 4 digits 1999, 2019
%y Year, 2 digits 99, 19
%c Full date-time, ISO 8601 2004-02-14T15:19:25+00:00
%r Full date-time, RFC 2822 Sat, 14 Feb 2015 16:01 +0200

Time Variables

Variable Description  Value
%g Hour, 12-hour, without leading zeros 1-12
%h Hour, 12-hour, with leading zeros 01-12
%G Hour, 24-hour, without leading zeros 0-23
%H Hour, 24-hour, with leading zeros 00-23
%i Minutes, with leading zeros 00-59
%s Seconds, with leading zeros 00-59
%a Lowercase am, pm
%A Uppercase AM, PM
%T Timezone abbreviation Ex., EST, PST

Note: The PHP date formats don’t natively allow for dots in am/pm (e.g., a.m. and p.m.), but for calendar events in LiveWhale you can choose to display them with dots by enabling <arg id="ampm_with_dots">true</arg> in your calendar widget settings.


Here are some examples of date format strings and result output that can be used in LiveWhale widgets.

The % sign means that the format character should represent a format variable and not a string that would display “as-is”.

Example Code Value
%F %j, %Y January 16, 2020
%F, %Y January, 2020
%l, %F %j%S, %Y Thursday, January 16, 2020
%g:%i %a 12:50 am
%Y/%m/%d 2020/01/16
%Y/%m/%d %g:%i %A 2020/01/16 10:26 AM
%M %j, %Y Jan 16, 2020
Current Date: %F %j%S Current Date: January 16th

Using AP Style

You can enable AP date and time formatting site-wide using the USE_AP_STYLE setting.

Customizing the timezone display

In cases where timezones get displayed on the front-end (like the calendar), you can override the default timezone abbreviations using the CUSTOMIZE_TIMEZONE_DISPLAY setting.

Formatting start_date and end_date in widget settings and API requests

In general, when setting start_date or end_date in your widget settings or API requests, LiveWhale supports any PHP-readable date string. This allows for great flexibility, for example:

Example Date Widget Setting LiveWhale Calendar — Inline Widget Setting API Request
-24 hours <arg id=”start_date”>-24 hours</arg> data-options=”id=123&start_date=-24 hours” /live/json/events/start_date/-24%20hours
-4 weeks <arg id=”start_date”>-4 weeks</arg> data-options=”id=123&start_date=-4 weeks” /live/json/events/start_date/-4%20weeks
last Friday <arg id=”start_date”>last Friday</arg> data-options=”id=123&start_date=last Friday” /live/json/events/start_date/last%20Friday
Sunday 11:59pm <arg id=”end_date”>Sunday 11:59pm</arg> data-options=”id=123&end_date=Sunday 11:59pm” /live/json/events/end_date/Sunday%2011:59pm
Saturday +4 weeks <arg id=”end_date”>Saturday +4 weeks</arg> data-options=”id=123&end_date=Saturday +4 weeks” /live/json/events/end_date/Saturday%20%2B4%20weeks
+1 year <arg id=”end_date”>Saturday +4 weeks</arg> data-options=”id=123&end_date=+1 year” /live/json/events/end_date/+1%20year

Using DD-MM vs MM/DD

However, when using specific date strings like 01-01-2024 or 04/03/2022, the default PHP date parsing works differently depending on the use of dashes vs slashes:

  • 04/06/2023 is interpreted month-first as April 6, 2023 (MM/DD/YYYY)
  • 04-06-2023 is interpreted day-first as June 4, 2023 (DD-MM-YYYY)

This can cause confusion since some LiveWhale contexts allow using either dashes or slashes (e.g., widget settings) and others require dashes (e.g., the REST API).

One way around this ambiguity is to use YYYY-MM-DD when setting up API integrations or overriding widget settings.

Or, you can enable the FILTER_USING_LOCAL_DATE_FORMAT setting to treat all date requests the same regardless of whether dashes or slashes are used.