diff --git a/docs/core/datetime.md b/docs/core/datetime.md new file mode 100644 index 0000000000..0bf6126972 --- /dev/null +++ b/docs/core/datetime.md @@ -0,0 +1,156 @@ +# 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 () + +## Components + +Date and DateTime ADF components are based on the following components: + +* Date Picker: +* DateTime Picker: + +## Adapters + +ADF 6.4.0 and later provides custom date and time adapters for library. + +### ADF DateFns Adapter + +The `AdfDateFnsAdapter` is an implementation of an Angular DateAdapter, +that provides backwards compatibility with the [moment.js](https://momentjs.com). + +The adapter works with both [moment.js](https://momentjs.com) and [date-fns](https://date-fns.org) 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. + +```ts +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) {} +} +``` + +The default set of ADF formats for Date picker components is as following: + +```ts +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: + +```ts +@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](https://momentjs.com). + +The adapter works with both [moment.js](https://momentjs.com) and [date-fns](https://date-fns.org) 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. + +```ts +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, + private dateTimeAdapter: DatetimeAdapter) {} +} +``` + +The default set of formatting rules, compared to the `moment.js` equivalents, is as following: + +```ts +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: + +```ts +@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 + +```ts +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](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/lib/core/src/lib/common/utils/date-fns-utils.spec.ts). diff --git a/docs/release-notes/RelNote-6.4.0.md b/docs/release-notes/RelNote-6.4.0.md new file mode 100644 index 0000000000..e6f1d1b235 --- /dev/null +++ b/docs/release-notes/RelNote-6.4.0.md @@ -0,0 +1,55 @@ +--- +Title: Release notes v6.3.0 +--- + +# Alfresco Application Development Framework (ADF) version 6.4.0 Release Note + +This document provides information on the Alfresco Application Development Framework **v6.4.0**. + +You can find release artifacts on [GitHub](https://github.com/Alfresco/alfresco-ng2-components/releases/tag/6.4.0). + +## Contents + +- [New Package Versions](#new-package-versions) +- [Features](#features) +- [Changelog](#changelog) +- [See Also](#see-also) + +## New Package Versions + +| Name | Version | +|--------------------------------|---------| +| @alfresco/js-api | 7.1.0 | +| @alfresco/adf-content-services | 6.4.0 | +| @alfresco/adf-process-services | 6.4.0 | +| @alfresco/adf-core | 6.4.0 | +| @alfresco/adf-insights | 6.4.0 | +| @alfresco/adf-extensions | 6.4.0 | +| @alfresco/adf-testing | 6.4.0 | +| @alfresco/adf-cli | 6.4.0 | + +## Features + +The suggested stack is: + +| Name | Version | +|------------|---------| +| Node | 18.x | +| npm | 8.x | +| Angular | 14.x | +| Typescript | 4.7 | + +For a complete list of changes, supported browsers and new feature please refer to the official documentation + +## Deprecations + +- `adfMomentDate` pipe is deprecated and no longer used by ADF components and apps +- `adfMomentDateTime` pipe is deprecated and no longer used by ADF components and apps +- custom `MomentDateAdapter` is deprecated and no longer used by ADF components and apps + +## Changelog + +## See Also + +- [Issue Tracker](https://github.com/Alfresco/alfresco-ng2-components/issues/new) +- [Discussion forum](http://gitter.im/Alfresco/alfresco-ng2-components)