@financial-times/o-date
Version:
JavaScript utilities for formatting and updating dates in the FT style. Also useful for formatting dates relative to the current time.
144 lines (103 loc) • 7.46 kB
Markdown
# o-date
o-date formats `time` elements in the FT style, and supports formatting dates in relative time.
- [Usage](#usage)
- [Markup](#markup)
- [JavaScript](#javascript)
- [Server-side](#server-side)
- [Migration](#migration)
- [Contact](#contact)
- [Licence](#licence)
## Usage
Check out [how to include Origami components in your project](https://origami.ft.com/documentation/components/#including-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](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-time-element). Add a standard `datetime` attribute in the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601). Then add the `data-o-component="o-date"` attribute with a class `o-date`.
```html
<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](https://origami.ft.com/documentation/components/compatibility/#core--enhanced-experiences) without JavaScript:
```html
<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](https://github.com/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-limit-24-hours`: always display a relative time but hide the `time` element if the `datetime` is older than 24 hours (e.g. `4 seconds ago`, `10 minutes ago`, `10 hours ago`).
- `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](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html): it is recommended to use a standard FT format but a [custom format](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html) may be used e.g. `h:mm a`.
Note: There used to be `time-ago-abbreviated` and `time-ago-abbreviated-limit-4-hours` options which are now both deprecated. These options still work but no longer show an abbreviated date. They will be removed in a future major version.
#### Text case
The formatted date defaults to all lower case (https://github.com/Financial-Times/ft-date-format/blob/master/index.js), e.g. `'an hour ago`.
Set `data-o-date-text-case=sentence` attribute on the `time` element to capitalise only the first letter of the text (e.g. `'An hour ago'`).
### 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 a relative time:
```html
<time data-o-component="o-date" class="o-date" datetime="2020-07-18T19:01:05.033Z" data-o-date-format="time-ago-limit-4-hours">
<!-- some arbitrary content -->
<span>updated at</span>
<!-- show the 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:
```html
<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-limit-4-hours" format here -->
<span data-o-date-printer data-o-date-format="time-ago-limit-4-hours"></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](https://origami.ft.com/documentation/components/initialising/).
For example call the `init` method to initialise all `o-date` instances on the page:
```js
import ODate from '@financial-times/o-date'
ODate.init();
```
Pass a specific element:
```js
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:
```js
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](https://github.com/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 | 6 | N/A | [migrate to v6](MIGRATION.md#migrating-from-v5-to-v6) |
⚠ maintained | 5 | N/A | [migrate to v5](MIGRATION.md#migrating-from-v4-to-v5) |
⚠ maintained | 4 | 4.2 | [migrate to v4](MIGRATION.md#migrating-from-v3-to-v4) |
⚠ maintained | 3 | 3.1 | [migrate to v3](MIGRATION.md#migrating-from-v2-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](https://github.com/Financial-Times/o-date/issues), visit [#origami-support](https://financialtimes.slack.com/messages/origami-support/) or email [Origami Support](mailto:origami-support@ft.com).
***
## Licence
This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).