Origami Frontend Components & Services

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:

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 'o-date'
ODate.init();

Pass a specific element:

import ODate from '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 '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

State Major Version Last Minor Release Migration guide
✨ active 4 N/A migrate to v4
⚠ maintained 3 3.1 migrate to v3
╳ deprecated 2 2.9 -
╳ deprecated 1 1.2 -

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.

Status
active Origami v1
Switch component view

GitHub Repository

Install o-date

If using the Build Service, add o-date@^4.1.2 to your script tag.

If running a Manual Build, run npm install "o-date@^4.1.2".

Help & Support

o-date is maintained directly by the Origami team. If you have any questions about o-date or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com