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.

Examples

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

Note: For API requests with no start/end date specified, results from the next 6 months will be returned. You can customize this site-wide by configuring json_month_range, rss_month_range, and ical_month_range.

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.