Readme: o-date

o-date formats time elements in the FT style, and supports formatting dates in relative time.

Usage

Check out how to include Origami components in your project to get started with o-date.

Markup

To render a human readable date in the FT format create a time element. Add a standard datetime attribute in the ISO 8601 format. Then add the data-o-component="o-date" attribute with a class o-date.

<time data-o-component="o-date" class="o-date" datetime="2000-06-14T23:00:00.000Z">
</time>

The rendered date will be a relative time or timestamp for a given date, in accordance with FT date formatting conventions E.g. 10 seconds ago, a minute ago, 3 hours ago, yesterday, July 18 2020.

Core Experience

We recommend a human readable date is added to the time element to support a core experience without JavaScript:

<time data-o-component="o-date" class="o-date" datetime="2000-06-14T23:00:00.000Z">
    June 15 2000
</time>

Node.js applications could provide a core experience fallback using the Financial-Times/ft-date-format library.

Format Options

Set the data-o-date-format attribute to customise how the time element is presented:

• date-only: only show the date, without relative or time information.
• time-ago-no-seconds: always display a relative time but if the relative time is under a minute display "Less than a minute ago" (e.g. Less than a minute ago, 10 minutes ago, an hour ago, 4 hours ago).
• time-ago-limit-4-hours: always display a relative time but hide the time element if the datetime is older than 4 hours (e.g. 4 seconds ago, 10 minutes ago, 4 hours ago).
• time-ago-abbreviated: always display a relative time with units abbreviated (e.g. 4s ago, 10m ago, 1h ago).
• time-ago-abbreviated-limit-4-hours: hide the time element when the datetime is older than 4 hours, otherwise render the same as time-ago-abbreviated.
• today-or-yesterday-or-nothing: display today if the datetime is today, yesterday if it was yesterday, or hide the time element if the datetime is older than yesterday.
• custom format: it is recommended to use a standard FT format but a custom format may be used e.g. h:mm a.

Copy Options

By default o-date will replace the contents of the time element with the formatted date. To include extra content alongside the formatted date add an element with the data-o-date-printer attribute. o-date will output the formatted date within the data-o-date-printer element and will not change other child elements.

For example to include "updated at" copy within the time element followed by an abbreviated relative time:

<time data-o-component="o-date" class="o-date" datetime="2020-07-18T19:01:05.033Z" data-o-date-format="time-ago-abbreviated">
    <!-- some arbitrary content -->
    <span>updated at</span>
    <!-- show the abbreviated time ago here in the printed element -->
    <!-- fallback to the date if o-date JavaScript fails  -->
    <span data-o-date-printer>
        20 July 2020
    </span>
</time>

Render a date multiple times within the same o-date component by including multiple data-o-date-printer elements. Each printer element may have a unique format by adding the data-o-date-format attribute. If data-o-date-format is not set on the printer element the parent data-o-date-format element will be used:

<time data-o-component="o-date" class="o-date" datetime="2020-07-18T19:01:05.033Z" data-o-date-format="date-only">
    <!-- render the date in the "date-only" format here -->
    <!-- (as set on the parent "time" element) -->
    <span data-o-date-printer></span>
    <!-- render the date in the "time-ago-abbreviated" format here -->
    <span data-o-date-printer data-o-date-format="time-ago-abbreviated"></span>
    <!-- render the date in the custom format "h:mm" here -->
    <span data-o-date-printer data-o-date-format="h:mm"></span>
</time>

Previously a CSS class o-date__printer was used instead of the data-o-date-printer attribute. The class o-date__printer is now deprecated.

JavaScript

Instantiate o-date JavaScript in the same way as other Origami components.

For example call the init method to initialise all o-date instances on the page:

import ODate from '@financial-times/o-date'
ODate.init();

Pass a specific element:

import ODate from '@financial-times/o-date'
const myDateElement = document.querySelector('#my-date');
ODate.init(myDateElement);

Or dispatch the o.DOMContentLoaded event to auto-construct all Origami components on the page, including each o-date element with a data-o-component="o-date" attribute:

import '@financial-times/o-date';
document.addEventListener('DOMContentLoaded', function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

o-date#destroy()

Call on any instances to stop processing date updates and release the item reference.

Server-side

See the npm package @financial-times/ft-date-format for server-side date formatting. Note: It's not recommended to output the 'time ago' server side as it will not be cacheable and will not update in the browser if the user leaves the page open for a prolonged period of time.

Migration

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.