LiveWhale Support

Documentation » Widget and API Settings » start_date

start_date

Starting date for widget items

Accepted values: any relative or absolute date string

Content types: Events

Related settings: end_date

data-options="id=123
/live/json/events

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:

  • -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”>+1 year</arg>
    • data-options=”id=123&end_date=+1 year”
    • /live/json/events/end_date/+1%20year

Combining relative start and end dates, you can do neat things like have a widget show the current academic year: 

<arg id="start_date">last July 1</arg>
<arg id="end_date">this June 30</arg>

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.

However, we don’t want developers thinking hard about the difference between 04-06 and 04/06. So, in LiveWhale 2.10.0 we’ve added a configuration setting which, when enabled, bypasses this dashes-vs-slashes question and always use one format across all settings and filters. 

$_LW->CONFIG['FILTER_USING_LOCAL_DATE_FORMAT']=true; // When true, widgets and API requests will treat all start and end dates as MM-DD-YYY (in US timezones) and DD-MM-YYYY in (European/Australian timezones), regardless of whether dashes or slashes were used.

With this setting enabled in global.config.php, all date strings will be treated as:

  • US timezones: month-first, i.e., MM-DD-YYYY or MM/DD/YYYY
  • European/Australian timezones: day-first, i.e., DD-MM-YYYY or DD/MM/YYYY

We expect this to become the default behavior in LiveWhale 3.0 but have implemented it as a configurable setting in the meantime to preserve backwards-compatibility for existing widgets and API requests across LiveWhale 2.x.

Common Settings

All Settings