Summary
When displaying the date and/or time, we follow the standards of the CLDR (Unicode Common Locale Data Repository)
- 4 styles. For both date and time, there are four different styles with different levels of detail.
- Styles. Don't mix styles in time + date combinations.
- Tooltip. Each time (whether absolute or relative) comes with a title attribute. This always contains the style
full, so that the user sees the weekday and time zone.
Related pages
Style guide: Tables
Storybook: Formatted date time
Storybook: Formatted relative time
Date and time format
Localized date, time and date-time formatting is not trivial. Depending on the country or language, there are different formats, habits or exceptions. Therefore, in wescale we follow the standard of CLDR for numerical and for linguistic notations. Basically, we distinguish four different styles (short, medium, long, full), each differing in its level of detail resp. length.
| Style | Date | Time | Date & Time |
|---|---|---|---|
short | 3/19/21 | 8:23 AM | 3/19/21, 8:23 AM |
medium | Mar 19, 2021 | 8:23:27 AM | Mar 19, 2021, 8:23:27 AM |
long | March 19, 2021 | 8:23:27 AM GMT | March 19, 2021 at 8:23:27 AM GMT |
full | Friday, March 19, 2021 | 8:23:27 AM GMT | Friday, March 19, 2021 at 8:23:27 AM GMT |
Relative time format
In addition to the absolute time, the relative time may also be of interest to the user in some cases. The timestamp can be in the past as well as in the future. Two years ago, last month, 3 minutes ago, tomorrow, in two weeks, ... - to name just a few of the possible values. These are also dependent on the user's language. Country specific words as well as pluralization of words is set automagically by the CLDR standards, so you don't have to worry about i18n and t10n here.
WUI use cases
Date & Time in combination with relative time
We use this format very often in tables for the create or last updated date. It is always set up in the same way. The relative time, then a line break, then the date and time combination in style medium. Overall, there is a tooltip with the absolute time and date in full style.
2 days ago
Mar 19, 2021, 8:23:27 AM
Time and milliseconds
The specification of milliseconds is in most cases completely irrelevant for the user. However, for technical dependencies, milliseconds can be decisive. In the support logs, for example, the time is therefore given in seconds and milliseconds.
hh:mm:ss.ms
08:50:21.644
Time range
With many time ranges, it is enough if they are accurate to the day. Here we use the date style medium without specifying a time. For the display of time ranges in tables, we use a separate column for the start and for the end value, so that sorting by both values is meaningful to the users.
Mar 19, 2021-Apr 19, 2021
Time zone
The time zone of a user is automatically set based on the respective user parameters. All times that a user sees within wescale are translated to his respective local time. So if a colleague from Australia creates an item after his morning tea at 09:45 AM, the user in New York will see the same item with a creation time of 6:45 PM of the previous day. For the page layout, it should always be taken into account that the display of timezones may be quite long.
More information about using and working with time zones can be found at www.w3.org/TR/timezone/
7:16:25 PM Australian Eastern Daylight Time
import WuiFormattedDateTime from "@wui/wui-vue/lib/formatted-date-time";
Example
<wui-formatted-date-time value="2021-03-15T15:00:00Z" />
Description
The WuiFormattedDateTime component displays formatted date and time. This component uses @wescale/intl and requires consuming applications to install the @wescale/vue-intl-plugin.
Note: Before using this component, make sure to read the WUI styleguide page regarding date & time formatting.
Input values
The following input values are supported:
- Date object
- ISO 8601 formatted string (e.g.,
2021-03-20T15:00:00Z) - Unix timestamp as defined by ECMAScript, i.e. the number of milliseconds elapsed since midnight on January 1, 1970, UTC (e.g.,
1616252400000)
Default title
By default, this component uses the full date and/or time format as HTML title. This gives users additional information such as weekday and time zone information. You can opt-out of this default behavior by passing a custom HTML title attribute to the component.
<wui-formatted-date-time value="2021-03-15T15:00:00Z" title="My custom title" />
Local dates
When formatting local dates without time component (floating time), keep in mind that JavaScript treats date-only ISO 8601 strings as UTC (i.e., 2021-03-20 is treated as 2021-03-20T00:00:00Z). Make sure to pass UTC as time zone in this case to prevent that the UTC offset of the time zone changes the date in the output format (e.g., 2021-03-20 -> 19.03.2021 with negative UTC offset, e.g. America/Los_Angeles with UTC-07:00).
<wui-formatted-date-time value="2021-03-15" timeZone="UTC" />
Properties
| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| value | [Date, String, Number] | true | Date object, ISO 8601 formatted string, or Unix timestamp | |
| dateStyle | String | medium | false | One of: short, medium, long, full |
| timeStyle | String | medium | false | One of: short, medium, long, full |
| timeZone | String | wescale user time zone* | false | IANA time zone identifier |
| tag | String | span | false | The wrapper HTML tag |
* Strictly speaking, this is the default time zone of the intl instance that is provided via the @wescale/vue-intl-plugin. In the wescale platform, where the intl instance provided at runtime via the shell, this is the wescale user time zone.
