mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2026-09-09 18:03:21 +00:00
Michal Kinas
5712f2742c
* [ACS-12451] Add missing ADF upgrade guides * [ACS-12451] CR fix * [ACS-12451] CR fixes
222 lines
16 KiB
Markdown
222 lines
16 KiB
Markdown
---
|
|
Title: Upgrading from ADF v8.1.1 to v8.2.1
|
|
---
|
|
|
|
# Upgrading from ADF v8.1.1 to v8.2.1
|
|
|
|
This guide provides instructions on how to upgrade your v8.1.1 ADF projects to v8.2.1 (covering the 8.2.0 and
|
|
8.2.1 releases).
|
|
|
|
## Before you begin
|
|
|
|
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps
|
|
below may involve code and theme changes — commit or back up your work first.
|
|
|
|
## Contents
|
|
|
|
- [Library updates](#library-updates)
|
|
- [Breaking changes](#breaking-changes)
|
|
- [Theming layer removed](#theming-layer-removed)
|
|
- [Removed deprecated components](#removed-deprecated-components)
|
|
- [Removed deprecated auth methods](#removed-deprecated-auth-methods)
|
|
- [Clipboard tooltip](#clipboard-tooltip)
|
|
- [OAuth `secret` removed](#oauth-secret-removed)
|
|
- [Dependency changes](#dependency-changes)
|
|
- [Other API changes](#other-api-changes)
|
|
- [Accessibility-driven changes](#accessibility-driven-changes)
|
|
- [New components and features](#new-components-and-features)
|
|
- [Behavioural changes](#behavioural-changes)
|
|
|
|
## Library updates
|
|
|
|
Update the `package.json` file with the latest library versions:
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"@alfresco/adf-core": "8.2.1",
|
|
"@alfresco/adf-content-services": "8.2.1",
|
|
"@alfresco/adf-process-services": "8.2.1",
|
|
"@alfresco/adf-process-services-cloud": "8.2.1",
|
|
"@alfresco/adf-insights": "8.2.1",
|
|
"@alfresco/adf-extensions": "8.2.1",
|
|
"@alfresco/js-api": ">=9.2.1"
|
|
}
|
|
}
|
|
```
|
|
|
|
Angular, Material, TypeScript, zone.js and Nx are unchanged from 8.1.1 (Angular 19.2). Clean `node_modules` and
|
|
`package-lock.json`, then `npm install`.
|
|
|
|
## Breaking changes
|
|
|
|
### Theming layer removed
|
|
|
|
The ADF SCSS theming layer was removed (`AAE-38524`). The public theming mixins **`alfresco-material-theme($theme)`**
|
|
and **`adf-core-theme($theme, $custom-css-variables)`** no longer exist, and neither do the `_theming.scss` /
|
|
`_typography.scss` entry points (the `$alfresco-typography` config is gone; `material.theme.scss`'s
|
|
`adf-material-theme()` mixin was renamed to `globals()`). ADF now inherits colours and typography directly from
|
|
your application's Angular Material theme with **no extra ADF theming step**.
|
|
|
|
If your app did:
|
|
|
|
```scss
|
|
@import '~@alfresco/adf-core/theming';
|
|
@include alfresco-material-theme($theme); // or @include adf-core-theme($theme);
|
|
```
|
|
|
|
remove those includes. The `--theme-*` / `--adf-theme-*` CSS variables are no longer generated by ADF — if you
|
|
rely on them, define them yourself under `:root`, mapping to Angular Material's system variables (e.g.
|
|
`--theme-primary-color: var(--mat-sys-primary);`) as shown in the updated theming docs. The ADF prebuilt themes
|
|
were already removed in 8.0.0.
|
|
|
|
### Removed deprecated components
|
|
|
|
The following long-deprecated items were removed (`ACS-10178`). Remove any imports/usages:
|
|
|
|
| Removed | Selector | Package |
|
|
| ----------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------- |
|
|
| `LoginDialogComponent`, `LoginDialogComponentData`, `LoginDialogService` | `adf-login-dialog` | `@alfresco/adf-core` |
|
|
| `AppListCloudComponent` | `adf-cloud-app-list` | `@alfresco/adf-process-services-cloud` |
|
|
| `AppDetailsCloudComponent` | `adf-cloud-app-details` | `@alfresco/adf-process-services-cloud` |
|
|
| `APP_LIST_CLOUD_DIRECTIVES` (const) | — | `@alfresco/adf-process-services-cloud` |
|
|
| `FormDefinitionSelectorCloudComponent` | `adf-cloud-form-definition-selector` | `@alfresco/adf-process-services-cloud` |
|
|
| `FormDefinitionSelectorCloudService`, `FormDefinitionSelectorCloudServiceInterface` | — | `@alfresco/adf-process-services-cloud` |
|
|
|
|
### Removed deprecated auth methods
|
|
|
|
The ECM/BPM-specific auth methods deprecated in 8.1.1 were **removed** (`ACS-9768`). Migrate:
|
|
|
|
- `isEcmLoggedIn()` / `isBpmLoggedIn()` → `isLoggedIn()` (use `isECMProvider()` / `isBPMProvider()` for the provider type).
|
|
- `getEcmUsername()` / `getBpmUsername()` → `getUsername()`.
|
|
- `BasicAlfrescoAuthService.getTicketEcm()` / `getTicketBpm()` were also removed.
|
|
|
|
These were removed from `AuthenticationServiceInterface`, `BaseAuthenticationService`, `AuthenticationService`,
|
|
`BasicAlfrescoAuthService` and `OidcAuthenticationService`.
|
|
|
|
### Clipboard tooltip
|
|
|
|
`ClipboardDirective` now uses Angular Material's tooltip instead of a bespoke component:
|
|
|
|
- **`ClipboardComponent` was removed** (along with the `adf-copy-content-tooltip` selector and the
|
|
`.adf-copy-tooltip` CSS / `clipboard.theme.scss`). Tests querying `.adf-copy-tooltip` must switch to `MatTooltipHarness`.
|
|
- `ClipboardDirective` is now `standalone` with a `MatTooltip` host directive; its constructor changed (adds
|
|
`MatTooltip` and `TranslateService`). Ensure Material animations are provided.
|
|
|
|
### OAuth `secret` removed
|
|
|
|
The `secret` field was removed from the OAuth2 configuration (`ACS-10592`): from `OauthConfigModel`, the js-api
|
|
`Oauth2Config`, and `app.config.schema.json`. A client secret should never be shipped in a browser app; remove
|
|
`oauth2.secret` from your `app.config.json`. (The token endpoint no longer receives a `client_secret`.)
|
|
|
|
### Dependency changes
|
|
|
|
- **`event-emitter` → `eventemitter3`** (`^5.0.1`). The `EventEmitter` type used by `AuthenticationService` and
|
|
the ADF HTTP client (and js-api) now comes from `eventemitter3` (new exported `EventEmitterInstance` /
|
|
`EventEmitterEvents` types). The `on/off/once/emit` API is compatible, but the type import origin changed.
|
|
- **`toPromise()` → `firstValueFrom` / `lastValueFrom`** internally (mechanical; single-emit sources, no behavioural change).
|
|
- **js-api** peer requirement raised to `>= 9.2.1`.
|
|
|
|
> The `superagent` HTTP client was **not** replaced — a replacement PR was reverted before 8.2.1, so `superagent`
|
|
> remains in place with no consumer impact.
|
|
|
|
### Other API changes
|
|
|
|
- **`ColumnsSelectorComponent.changeColumnVisibility`** signature changed from `(dataColumn: DataColumn)` to
|
|
`(event: MatSelectionListChange)` (the columns list was rewritten to `mat-selection-list`).
|
|
- **`FormBaseComponent.completeTaskForm(outcome?)`** gained a second `outcomeId?: string` argument (and outcome
|
|
completion now requires the outcome's `id`); `FormCloudComponent.completeForm`/`completeTaskForm` follow suit.
|
|
Subclasses overriding these must update.
|
|
- **`DisplayRichTextWidgetComponent`** constructor changed (the `sanitizer` param was removed; parsing moved to
|
|
the new `RichTextParserService`).
|
|
- **`ReactiveFormWidget`** interface now requires a `field: FormFieldModel` member; new `MaybeReactiveFormWidget`
|
|
type and `FormFieldTypes.isReactiveWidget(...)`.
|
|
- **`MaxLengthFieldValidator`** constructor now takes optional `(supportedTypes, maxLength)`; `FORM_FIELD_VALIDATORS`
|
|
gained an entry that caps NUMBER fields at 10 digits.
|
|
- **`AmountWidgetComponent`** constructor changed (adds `CurrencyPipe`, `TranslationService`); `ADF_AMOUNT_SETTINGS`
|
|
was widened to accept `Observable<AmountWidgetSettings> | AmountWidgetSettings`; any custom `TranslationService`
|
|
must implement the new `getLocale()`.
|
|
- **`SearchFilterAutocompleteChipsComponent`** constructor now requires `SitesService` (for the new LOCATION facet).
|
|
- Base `WidgetComponent` no longer registers a host `(click)` binding — widgets that need it now declare their own.
|
|
- The screen `screen-cloud.model` import path moved under `components/screen-cloud/user-task-screen/` (deep imports must update).
|
|
- **`DataTableCellComponent`** (the base cell class): the public `computedTitle: string` property was replaced by a
|
|
`title = computed(...)` signal (backed by `protected rawComputedTitle`), and `computeTitle()` changed from
|
|
`private` to `protected`. Custom cells subclassing it should override `protected computeTitle()` and read `title()`.
|
|
- **`StartProcessCloudComponent`**: the public field `customOutcome` was split into `customOutcomeName` +
|
|
`customOutcomeId`, and `onCustomOutcomeClicked(outcome)` now takes a `FormOutcomeEvent` (was `string`);
|
|
`FormModel.selectedOutcome` is no longer `readonly`.
|
|
- **`UserTaskCloudComponent.onCompleteTask()`** gained a second optional `taskType?: UserTaskType` argument.
|
|
- **`BasicAlfrescoAuthService.getTicketEcmBase64()`** return type narrowed from `string | null` to `string`.
|
|
- **`ProcessFilterCloudModel`** — most properties were widened to `| null` and `parentId` became non-optional
|
|
(relevant to strict-typed consumers constructing the model).
|
|
|
|
### Accessibility-driven changes
|
|
|
|
A large accessibility batch (`ACS-10xxx`) added aria labels/roles and keyboard handling. Most are additive, but a
|
|
few change the DOM or public members that tests/styles may depend on:
|
|
|
|
- `LibraryDialogComponent` — `@Output() success` type narrowed to `EventEmitter<SiteEntry>`; `visibilityOption`
|
|
is now a `string` (the option value, not the option object).
|
|
- `NotificationHistoryComponent` — its `storageService` / `cd` constructor members are now `private` (were public);
|
|
the mark-as-read control changed from a `mat-menu-item` with `id="adf-notification-history-mark-as-read"` to an
|
|
icon button exposing `data-automation-id="adf-notification-history-mark-as-read"` (the `id` was removed).
|
|
- `DynamicChipListComponent` — the chip set changed `role="listbox"` → `role="list"` (chips are now `listitem`).
|
|
- Confirm dialog — the **Yes/No buttons swapped order** and initial focus moved to the accept button; e2e relying
|
|
on positional order or initial focus on "No" must update.
|
|
- Datatable header — the `$thumbnail` column screen-reader title changed from the literal `'Thumbnail'` to the
|
|
i18n key `ADF-DOCUMENT-LIST.LAYOUT.THUMBNAIL`.
|
|
- A few existing i18n key **values** changed (e.g. `BREADCRUMB.ARIA-LABEL.DROPDOWN`, and
|
|
`CORE.METADATA.ACCESSIBILITY.EDIT` is now parameterised with `{{ sectionName }}`), plus many new keys were added.
|
|
|
|
## New components and features
|
|
|
|
- **Repeatable-section form widget** — `RepeatWidgetComponent` (`adf-repeat-widget`, new
|
|
`FormFieldTypes.REPEATABLE_SECTION = 'repeatable-section'`) renders add/remove-row repeatable sections
|
|
(with `initialNumberOfRows` / `maxNumberOfRows` / `allowInitialRowsDelete` params and a confirm-on-remove dialog).
|
|
New `ContainerRowModel`; `FormFieldModel` gained `rows`, `addRow()`, `removeRow()`, `canAddRow()`.
|
|
- **Button form widget** — `ButtonWidgetComponent` (`button-widget`, new `FormFieldTypes.BUTTON = 'button'`),
|
|
auto-registered in `FormRenderingService`.
|
|
- **SSO integration API** (js-api) — `IntegrationSSOApi.getAccountInformation(repositoryId)` +
|
|
`SSOUserAccountCredentialsRepresentation`.
|
|
- **Screens on the start-process event** — `StartProcessScreenCloudComponent`
|
|
(`adf-cloud-start-process-screen-cloud`), an abstract `BaseScreenCloudComponent`, and a `TaskTypeResolverService`
|
|
(+ `UserTaskContentType`) to resolve form vs screen tasks.
|
|
- **Count APIs** — `ProcessListCloudService.getProcessListCount(...)` and `TaskListCloudService.getTaskListCount(...)`
|
|
(dedicated `/count` endpoints, used by the filter components in POST mode).
|
|
- **Custom redirects** — `StartProcessCloudComponent` gained `@Output() customOutcomeSelected` (emits the outcome
|
|
id); `FormModel.selectedOutcomeId` was added.
|
|
- **Rich-text parsing service** — `RichTextParserService` + `RICH_TEXT_PARSER_TOKEN`; `editorjs-html` moved to `dependencies`.
|
|
- **Legacy saved searches** — `SavedSearchesService` refactored onto a `SavedSearchStrategy` base with a new
|
|
`SavedSearchesLegacyService` and an optional `SAVED_SEARCHES_SERVICE_PREFERENCES` token.
|
|
- **Amount locale display** — opt-in via `AmountWidgetSettings.enableDisplayBasedOnLocale` (formats via `CurrencyPipe`
|
|
by browser locale); new `TranslationService.getLocale()`.
|
|
- **Search** — `SearchDateRangeComponent` gained `@Input() onReset$` + `reset()`; a new LOCATION (`SITE`) autocomplete
|
|
facet (filtered to accessible sites); chip autocomplete now reacts to `preselectedOptions` changes.
|
|
- Model additions: `ApplicationInstanceModel.lastModifiedAt` and `quickRunDeployment`; `QueryParams.include` widened
|
|
to `string`; new `AppConfigValues.OOI_CONNECTOR_URL` (`ooiServiceUrl`) for Microsoft 365 sessions under Basic auth.
|
|
- **`ProcessListCloudComponent`** gained `@Input() excludeByProcessCategoryName` (with a matching
|
|
`ProcessFilterCloudModel` field) so admins can filter out form-specific processes.
|
|
- New exported form internals: `RepeatableSectionModel` and `ROW_ID_PREFIX` (moved out of `form-field.model` into
|
|
`repeatable-section.model`), and `formFieldRuleHandler` (`handlers/form-field-rule.handler`) — enables conditional
|
|
(dependent) dropdowns inside repeatable sections to resolve per-row.
|
|
- `convertObjectToFormData` now accepts `Array<string | Blob>` values (multi-valued property upload).
|
|
|
|
## Behavioural changes
|
|
|
|
| Area | Change |
|
|
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Forms — number | Integer/number fields reject input longer than 10 digits. |
|
|
| Forms — dropdown | Multi-select dropdowns work again (value writes are debounced by 100 ms); conditional dropdowns inside repeatable sections resolve per-row. |
|
|
| Forms — click | The form widget `event` handler fires once per click (a double-registration was removed from the base widget). |
|
|
| Forms — start process | The process card/start button render only after the form finishes loading (no button flash); setting the process definition programmatically no longer triggers a reload. |
|
|
| Search | Queries with non-latin characters are now UTF-8 base64-encoded correctly; resetting the tabbed date filter clears each tab. |
|
|
| Viewer | Changing the version inside the viewer reloads the preview; task-attached files with a display-value form field preview correctly. |
|
|
| Clipboard | Copy affordance is now a Material tooltip; copying keeps focus on the trigger (e.g. the "Copy link" button). |
|
|
| Localisation | Portuguese dates render `dd/mm/yyyy`; `TimeAgoPipe` is now impure and reacts to runtime locale changes, as do date/filesize datatable cells. |
|
|
| Auth | Under Basic auth, requests to the OOI service receive the content-services ticket (fixes starting a Microsoft 365 session). |
|
|
| Notifications / WebSocket | `WebSocketService.connectionParams` is now a function, so the auth token is re-evaluated on every (re)connect — deployment/websocket updates arrive without closing the panel. |
|
|
| Saved searches | `SavedSearchesService` now falls back to the preferences API on error (and re-throws non-404 errors during migration), fixing an empty sidebar on the first login after a cache clear. |
|
|
| Forms — start process | The default start-process error i18n key was corrected (the previous fallback key did not exist, so no error message showed). |
|
|
| Forms — button widget | `ButtonWidgetComponent` no longer uses `OnPush`, so its disabled state updates when the field object mutates in place. |
|
|
| Card view | Text/date item labels now always float (`floatLabel="always"`); the editable date item gained an `adf-property-field` class. |
|