mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-05-12 17:04:57 +00:00
[APPS-2255] documentation on date adapters (#9008)
* release note placeholder * datetime docs * fix docs * fix docs
This commit is contained in:
Denys Vuika
GitHub
parent
d500bc67d7
commit
cda12730f6
156
docs/core/datetime.md
Normal file
156
docs/core/datetime.md
Normal file
@ -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 (<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](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<Date>) {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
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<Date>,
|
||||||
|
private dateTimeAdapter: DatetimeAdapter<Date>) {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
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).
|
||||||
55
docs/release-notes/RelNote-6.4.0.md
Normal file
55
docs/release-notes/RelNote-6.4.0.md
Normal file
@ -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)
|
||||||
Loading…
x
Reference in New Issue
Block a user