alfresco-ng2-components/docs/core/datetime.md

Date and Time

As of v.6.4.0 the ADF is no longer using moment.js for date and time processing. This is related to the `moment.js`` sunset (https://momentjs.com/docs/?/displaying/format/#/-project-status/)

Components

Date and DateTime ADF components are based on the following components:

• Date Picker: https://v14.material.angular.io/components/datepicker/
• DateTime Picker: https://kuhnroyal.github.io/mat-datetimepicker/

Adapters

ADF 6.4.0 and later provides custom date and time adapters for https://date-fns.org/ library.

ADF DateFns Adapter

The AdfDateFnsAdapter is an implementation of an Angular DateAdapter, that provides backwards compatibility with the moment.js.

The adapter works with both moment.js and date-fns formats, and dynamically translates moment.js formatting tokens to date-fns.

In addition, the adapter automatically detects the current locale and switches to the corresponding values.

import { DateAdapter, MAT_DATE_FORMATS } from '@angular/material/core';
import { AdfDateFnsAdapter, ADF_DATE_FORMATS } from '@alfresco/adf-core';

@Component({
    providers: [
        { provide: MAT_DATE_FORMATS, useValue: ADF_DATE_FORMATS },
        { provide: DateAdapter, useClass: AdfDateFnsAdapter }
    ]
})
export class MyComponent() {
    constructor(private dateAdapter: DateAdapter<Date>) {}
}

The default set of ADF formats for Date picker components is as following:

export const ADF_DATE_FORMATS: MatDateFormats = {
    parse: {
        dateInput: 'dd-MM-yyyy'
    },
    display: {
        dateInput: 'dd-MM-yyyy',
        monthLabel: 'LLL',
        monthYearLabel: 'LLL uuuu',
        dateA11yLabel: 'PP',
        monthYearA11yLabel: 'LLLL uuuu'
    }
};

You can provide own format defaults by injecting a different MAT_DATE_FORMATS value:

@Component({
    providers: [
        { provide: MAT_DATE_FORMATS, useValue: MY_CUSTOM_FORMATS }
    ]
})

ADF DateTimeFns Adapter

The AdfDateTimeFnsAdapter is an implementation of the mat-datetimepicker DateTimeAdapter, that provides backwards compatibility with the moment.js.

The adapter works with both moment.js and date-fns formats, and dynamically translates moment.js formatting tokens to date-fns.

In addition, the adapter automatically detects the current locale and switches to the corresponding values.

import { DateAdapter, MAT_DATE_FORMATS } from '@angular/material/core';
import { DatetimeAdapter, MAT_DATETIME_FORMATS } from '@mat-datetimepicker/core';
import { 
    ADF_DATE_FORMATS, 
    ADF_DATETIME_FORMATS, 
    AdfDateFnsAdapter, 
    AdfDateTimeFnsAdapter 
} from '@alfresco/adf-core';

@Component({
    providers: [
        { provide: MAT_DATE_FORMATS, useValue: ADF_DATE_FORMATS },
        { provide: MAT_DATETIME_FORMATS, useValue: ADF_DATETIME_FORMATS },
        { provide: DateAdapter, useClass: AdfDateFnsAdapter },
        { provide: DatetimeAdapter, useClass: AdfDateTimeFnsAdapter }
    ]
})
export class MyComponent() {
    constructor(private dateAdapter: DateAdapter<Date>,
        private dateTimeAdapter: DatetimeAdapter<Date>) {}
}

The default set of formatting rules, compared to the moment.js equivalents, is as following:

export const ADF_DATETIME_FORMATS: MatDatetimeFormats = {
    parse: {
        dateInput: 'P', // L
        monthInput: 'LLLL', // MMMM
        timeInput: 'p', // LT
        datetimeInput: 'Pp' // L LT
    },
    display: {
        dateInput: 'P', // L
        monthInput: 'LLLL', // MMMM
        datetimeInput: 'Pp', // L LT
        timeInput: 'p', // LT
        monthYearLabel: 'LLL uuuu', // MMM YYYY
        dateA11yLabel: 'PP', // LL
        monthYearA11yLabel: 'LLLL uuuu', // MMMM YYYY
        popupHeaderDateLabel: 'ccc, dd MMM' // ddd, DD MMM
    }
};

You can provide own format defaults by injecting a different MAT_DATETIME_FORMATS value:

@Component({
    providers: [
        { provide: MAT_DATETIME_FORMATS, useValue: MY_CUSTOM_FORMATS }
    ]
})

Date Utils

If you need lower-level manipulations with dates, ADF provides DateFnsUtils that addresses various scenarios like:

• converting moment.js format tokens to date-fns
• parsing dates from strings, with moment.js/date-fns formatting tokens
• formatting dates as strings, using moment.js/date-fns formatting tokens
• validating dates
• converting UTC to Local datetime, or Local to UTC

import { DateFnsUtils } from '@alfresco/adf-core';

// format using moment.js tokens
const momentString = DateFnsUtils.formatDate(new Date(), 'll');

// format using date-fns tokens
const dateFnsString = DateFnsUtils.formatDate(new Date(), 'PP');

You can find more details on the format conversion in the DateFnsUtils unit tests.