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
244 lines
16 KiB
Markdown
244 lines
16 KiB
Markdown
---
|
|
Title: Upgrading from ADF v7.0 to v8.0
|
|
---
|
|
|
|
# Upgrading from ADF v7.0 to v8.0
|
|
|
|
This guide provides instructions on how to upgrade your v7.0.0 ADF projects to v8.0.0.
|
|
|
|
**v8.0.0 is a major release.** It moves ADF from Angular **17 to 19** (via internal 18 → 19 steps), upgrades
|
|
**`@ngx-translate/core` to v16** and **`@alfresco/js-api` to v9**, upgrades **pdf.js from 3.x to 5.x**, and
|
|
performs a large **theming clean-up** (the prebuilt themes and the ADF colour/variable SCSS partials are removed).
|
|
Budget time to migrate your Angular version, your theme, your i18n bootstrap, and your PDF viewer worker asset.
|
|
|
|
## Before you begin
|
|
|
|
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Because this is
|
|
a major version with many breaking changes, build, run and re-test your application after upgrading.
|
|
|
|
## Contents
|
|
|
|
- [Library updates](#library-updates)
|
|
- [Major platform changes](#major-platform-changes)
|
|
- [Breaking changes](#breaking-changes)
|
|
- [Angular 19 and standalone](#angular-19-and-standalone)
|
|
- [Internationalisation (i18n)](#internationalisation-i18n)
|
|
- [Theming clean-up](#theming-clean-up)
|
|
- [PDF viewer (pdf.js 5)](#pdf-viewer-pdfjs-5)
|
|
- [Viewer components](#viewer-components)
|
|
- [API signature and model changes](#api-signature-and-model-changes)
|
|
- [Constructor / DI changes](#constructor--di-changes)
|
|
- [Removed roles and DOM hooks](#removed-roles-and-dom-hooks)
|
|
- [Deprecations](#deprecations)
|
|
- [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.0.0",
|
|
"@alfresco/adf-content-services": "8.0.0",
|
|
"@alfresco/adf-process-services": "8.0.0",
|
|
"@alfresco/adf-process-services-cloud": "8.0.0",
|
|
"@alfresco/adf-insights": "8.0.0",
|
|
"@alfresco/adf-extensions": "8.0.0",
|
|
"@alfresco/js-api": ">=9.0.0",
|
|
"@ngx-translate/core": ">=16.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
|
|
|
|
```sh
|
|
npm install
|
|
```
|
|
|
|
## Major platform changes
|
|
|
|
| Area | 7.0.0 | 8.0.0 |
|
|
| ----------------------------------- | ---------- | ----------------- |
|
|
| Angular / Material / CDK | 17.1 | **19.2** |
|
|
| TypeScript | 5.3 | **5.8.2** |
|
|
| zone.js | 0.14.8 | **0.15.0** |
|
|
| Nx | 20.0 | **20.8** |
|
|
| `@ngx-translate/core` | 14/15 | **>= 16.0.0** |
|
|
| `apollo-angular` / `@apollo/client` | 6.0 / 3.11 | **10.0.3 / 3.13** |
|
|
| `pdfjs-dist` | 3.3 | **5.1.91** |
|
|
| `@alfresco/js-api` | >= 8.0.0 | **>= 9.0.0** |
|
|
|
|
Angular Material remains on the **M2 (Material 2) theming APIs** in 8.0.0 — the Material Design 3 migration was
|
|
deferred. Move your own application to Angular 19 / TypeScript 5.8 / zone.js 0.15 / Nx 20.8 in lockstep, and
|
|
upgrade `apollo-angular` (a major bump) if you use GraphQL.
|
|
|
|
The declared `engines.node` floor is unchanged (`>=18.0.0`), but the version the libraries are **built and tested
|
|
on** moved from Node 20 to **Node 22** (`.nvmrc` `20.18.1` → `22.14.0`) — align your build/CI Node version.
|
|
|
|
## Breaking changes
|
|
|
|
### Angular 19 and standalone
|
|
|
|
- Migrate your application to Angular 19. Standalone is the default in Angular 19, so the redundant
|
|
`standalone: true` flags were dropped from ADF components. Any app NgModule that still **declares** ADF
|
|
components must import them as standalone instead.
|
|
|
|
### Internationalisation (i18n)
|
|
|
|
`@ngx-translate/core` v16 changed how translation is wired, and `CoreModule` was modernised:
|
|
|
|
- **`CoreModule` no longer re-exports `TranslateModule`.** Components that used the `translate` pipe via a
|
|
transitive `TranslateModule` must now import ngx-translate's standalone `TranslatePipe` (or provide translation
|
|
themselves).
|
|
- **`CoreModule.forRoot()` no longer auto-provides `MomentDateAdapter`, `TranslateStore`, or `TranslateService`**
|
|
(translation now uses `provideTranslateService`), and no longer re-exports `HttpClientModule` / the XSRF module
|
|
(HTTP is wired via `provideHttpClient(...)`). Provide these yourself if you depended on them transitively.
|
|
- Prefer the new standalone providers (see [New components and features](#new-components-and-features)):
|
|
`provideI18N(...)`, `provideAppConfig()`, `provideShellRoutes(...)` (`ShellModule` is deprecated),
|
|
`provideHttpClient()`.
|
|
|
|
### Theming clean-up
|
|
|
|
The ADF theming layer was significantly reduced (`AAE-34390`/`AAE-34439`/`AAE-34458`). This is the biggest
|
|
source of build/visual breakage for apps with custom themes:
|
|
|
|
- **Prebuilt themes were removed** — the `lib/core/src/lib/styles/prebuilt/*` themes (`adf-blue-orange`,
|
|
`adf-indigo-pink`, etc.) no longer ship. Replace any `@import '@alfresco/adf-core/prebuilt-themes/...'` with a
|
|
custom theme (`mat.define-palette` + `mat.define-light-theme` + `@include alfresco-material-theme($theme)`) or
|
|
an Angular Material prebuilt theme.
|
|
- **The colour / variable SCSS partials were deleted**: `_colors.scss` (palettes `$alfresco-ecm-blue`,
|
|
`$alfresco-accent-orange`, `$alfresco-warn`, the `$black-*/-white-*-opacity` helpers, …), `_reference-variables.scss`
|
|
(all `$adf-ref-*`), and `_components-variables.scss` (the `adf-components-variables($theme)` mixin). Redefine any
|
|
of these you referenced in your own theme.
|
|
- **Many `--adf-*` component CSS custom properties were removed** (card-view, info-drawer tabs, people/group-cloud,
|
|
header icon-button, edit-task/process-filter, package-list, about-*, identity-user-info, etc.) — these are no
|
|
longer overridable via CSS variables. A small set of metadata/error/secondary-button/chip/sidenav custom
|
|
properties is retained.
|
|
- **Removed mixins:** `adf-components-variables($theme)` and `adf-snackbar-theme`. The snackbar classes
|
|
`.adf-error-snackbar` / `.adf-warning-snackbar` / `.adf-info-snackbar` are no longer coloured by ADF — style them
|
|
in your app.
|
|
- **Default font changed** from `Muli` to `Roboto`.
|
|
- Form widgets no longer render a custom `.adf-asterisk` span for required fields (the native Material required
|
|
marker is used); a new `.adf-form-field-input` class was added, with placeholder-conditional `floatLabel`.
|
|
- Docs removed: `basic-theming.md`, `typography.md`, and the "using a prebuilt theme" section of `theming.md`.
|
|
|
|
### PDF viewer (pdf.js 5)
|
|
|
|
`pdfjs-dist` was upgraded from 3.x to **5.1.91**, which changes how the worker is loaded:
|
|
|
|
- The worker asset was renamed from `pdf.worker.min.js` to **`pdf.worker.min.mjs`**. Update your build's asset copy
|
|
(`node_modules/pdfjs-dist/build/pdf.worker.min.mjs`). The component now fetches the worker and loads it via a
|
|
Blob `workerPort` (to tolerate servers that return the wrong MIME type for `.mjs`).
|
|
- New overridable injection tokens `PDFJS_MODULE` and `PDFJS_VIEWER_MODULE`.
|
|
- pdf.js scale values are now strings (`isSameScale(oldScale: string, newScale: string)`), and the viewer container
|
|
now also carries the native `pdfViewer` class.
|
|
|
|
### Viewer components
|
|
|
|
- **`ViewerRenderComponent` `@Input() isLoading` was removed** — loading state is now managed internally and cleared
|
|
via child-renderer completion outputs / a new public `markAsLoaded()`. Remove any `[isLoading]` binding. Custom
|
|
viewer/preview-extension components should emit a `contentLoaded` output (new on `TxtViewerComponent` and
|
|
`PreviewExtensionComponent`; `imageLoaded`/`canPlay`/`pagesLoaded` on the built-in renderers) to clear the spinner.
|
|
- **`AlfrescoViewerComponent`** — `readOnly` is now a public `@Input()` (previously an internal permission-derived
|
|
field; the permission result moved to an internal `canEditNode`). New `@Input() showToolbarDividers` (also on core
|
|
`ViewerComponent`, which gained an `adf-viewer-inline` host class when not in overlay mode).
|
|
|
|
### API signature and model changes
|
|
|
|
- **`TagService.createTags(tags)`** now returns `Observable<TagEntry | TagPaging>` (was `Observable<TagEntry[]>`).
|
|
Read results via `result.list.entries[i].entry.tag`; import `TagPaging` from `@alfresco/js-api`. The `refresh`
|
|
output now emits the paging object.
|
|
- **`AspectListService` was reworked** — `getAspects()`, `getStandardAspects()` and `getCustomAspects()` were
|
|
removed/repurposed. `getAspects(whiteList, opts?)` now takes a whitelist and returns `AspectPaging` (not
|
|
`AspectEntry[]`); new `getAllAspects(...)` returns a new `CustomAspectPaging`. New exported `StandardAspectsWhere`
|
|
/ `CustomAspectsWhere`.
|
|
- **Knowledge Retrieval / Search-AI models changed** (`@alfresco/js-api`): `AiAnswer.questionId` → `question`,
|
|
`AiAnswer.references` → `objectReferences` (new `AiAnswerObjectReference`), new `AiAnswer.complete`;
|
|
`AiAnswerReference.referenceText` was replaced by `rank` / `rankScore`.
|
|
- **`FormBaseComponent.hasVisibleOutcomes` getter was removed** — outcome visibility now lives in a new exported
|
|
pure helper `isOutcomeButtonVisible(...)` (from the new `form/buttons-visibility` public export).
|
|
- **`UserTaskCloudComponent.taskCompleted`** now emits `boolean` (the "open next task" flag) instead of the task id
|
|
`string`; `TaskScreenCloudComponent.taskCompleted` / `UserTaskCustomUi.taskCompleted` were retyped.
|
|
- `WidgetComponent.isRequired()` return type narrowed from `any` to `boolean` (returns `false`, not `null`, when not required).
|
|
- **APS (classic) task-filter methods renamed**: `TaskFilterService.getInvolvedTasksFilterInstance` →
|
|
`getOverdueTasksFilterInstance`, `getQueuedTasksFilterInstance` → `getUnassignedTasksFilterInstance`; the default
|
|
filters changed from "Involved/Queued" to "Overdue/Unassigned" (existing user filters are auto-migrated on load).
|
|
- Dropdown form fields: `FormFieldModel.value` may now be the full option object `{ id, name }` rather than a string id.
|
|
|
|
### Constructor / DI changes
|
|
|
|
Only relevant if you manually instantiate or subclass these:
|
|
|
|
- `NodeFavoriteDirective` / `LibraryFavoriteDirective` constructors gained `NotificationService`.
|
|
- `AlfrescoApiLoaderService` constructor gained a `SecurityOptionsLoaderService` dependency.
|
|
|
|
### Removed roles and DOM hooks
|
|
|
|
Update e2e/CSS selectors:
|
|
|
|
- The datatable row checkbox no longer has `role="checkbox"` (use `data-adf-datatable-row-checkbox` / `[attr.aria-checked]`).
|
|
- The add-user/group search results no longer have `role="listbox"`.
|
|
- The viewer file-name spans `.adf-viewer__display-name-without-extension` / `-extension` were replaced by a single
|
|
span; a new public `ViewerComponent.displayName` (middle-ellipsised at 50 chars) is available.
|
|
|
|
## Deprecations
|
|
|
|
These still work in 8.0.0 but are slated for removal — migrate when you upgrade:
|
|
|
|
- **`ShellModule`** → use **`provideShell(opts?)`** (`@alfresco/adf-core/shell`), which takes
|
|
`{ routes, appService?, authGuard?, navBar? }` and wires the whole shell (see
|
|
[New components and features](#new-components-and-features)).
|
|
- **`FormBaseModule`** (`@alfresco/adf-core`) → import the standalone form components directly.
|
|
- **`CoreTestingModule`** (`@alfresco/adf-core`) → use the standalone components in your test beds.
|
|
- **`ProcessServicesCloudModule`** (`@alfresco/adf-process-services-cloud`) → import the standalone components
|
|
directly, or replicate the module with providers:
|
|
```ts
|
|
providers: [
|
|
provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud'),
|
|
provideCloudPreferences(),
|
|
provideCloudFormRenderer(),
|
|
{ provide: TASK_LIST_CLOUD_TOKEN, useClass: TaskListCloudService }
|
|
]
|
|
```
|
|
- **Dialog / snackbar NgModules** are now `@deprecated` — import the standalone component directly instead of the
|
|
module: `ConfirmDialogModule`, `EditJsonDialogModule`, `UnsavedChangesDialogModule`, `SnackbarContentModule`
|
|
(`@alfresco/adf-core`) and `DownloadZipDialogModule` (`@alfresco/adf-content-services`).
|
|
|
|
(The theming layer / prebuilt themes are covered under [Theming clean-up](#theming-clean-up).)
|
|
|
|
## New components and features
|
|
|
|
- **`provideI18N(config?)`** (core) — standalone i18n bootstrap: `provideI18N({ defaultLanguage: 'en', assets: [['app', '/assets/i18n']] })`. Wraps `provideTranslateService` + `provideTranslations` (both still available).
|
|
- **`provideShell(opts?)`** (`@alfresco/adf-core/shell`) — the recommended replacement for the deprecated
|
|
`ShellModule`; it takes `{ routes, appService?, authGuard?, navBar? }` and wires the whole shell (calling the
|
|
narrower **`provideShellRoutes(routes)`** helper internally). Plus **`provideAppConfig()`**,
|
|
**`provideCloudPreferences()`** and **`provideCloudFormRenderer()`** — standalone provider helpers.
|
|
- **`auth.withCredentials`** — a new `app.config.json` key (`AppConfigValues.AUTH_WITH_CREDENTIALS`) that controls the
|
|
HTTP `withCredentials` flag, so it can be disabled for identity providers that reject credentials. A new
|
|
`SecurityOptionsLoaderService` (content-services) applies it early during bootstrap.
|
|
- **New outputs / methods:** `CommentsComponent` / `NodeCommentsComponent` `@Output() commentAdded`;
|
|
`ProcessContentService.getContentRenditionTypePreview(contentId)`; `StorageService.getItems()`;
|
|
`TaskFilterService.updateTaskFilter(...)`.
|
|
- **Records management:** new `FilePlansApi.getFilePlanRoles(...)` plus `FilePlanRole*` models (js-api), used to verify legal-hold capabilities and hide the RM library join button when unauthorised.
|
|
- **Process / forms:** an "Open next task" checkbox for screen-based tasks (`UserTaskCloudComponent` /
|
|
`TaskScreenCloudComponent` gained `@Input() showNextTaskCheckbox`, `isNextTaskCheckboxChecked` and
|
|
`@Output() nextTaskCheckboxCheckedChanged`); `ProcessDefinitionCloud.constantValues` (new `ConstantValues` type);
|
|
`rootProcessInstanceId` propagated to dynamic task screens; the Data Table widget now renders empty tables and a
|
|
preview placeholder instead of erroring; `FormCloudComponent.showCompleteButton` input.
|
|
- **Categories dialog** now validates prohibited symbols (`: " \ | < > / ? *`) and trailing dots.
|
|
- Favorite directives now show snackbar notifications; the `<html lang>` attribute now updates on language change.
|
|
|
|
## Behavioural changes
|
|
|
|
| Area | Change |
|
|
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Document list | Navigating to a new folder now resets the active `filterValue`; custom column visibility/order/width persist across refresh. |
|
|
| Forms | Hidden required dropdowns are no longer invalid; clearing a numeric field stores `null` (not `''`); required dropdowns show a single asterisk; async form enrichment now populates date fields and hides the spinner correctly; `onProcessFinish` fires reliably from `onFormLoaded`. |
|
|
| Content metadata | Content in non-edited panels stays visible while another panel is edited (new `isPanelEditing(panelTitle)` / `editedPanelTitle`). |
|
|
| Aspect list | All aspects are fetched (paged) when the first call doesn't return them all. |
|
|
| Viewer | Loading state is driven by renderer completion; PDF documents scale correctly; the image viewer is no longer cropped; the file name is truncated with a tooltip. |
|
|
| Accessibility | Loading bars/spinners gained aria labels; nested interactive controls were removed from the datatable; form tab navigation uses a focus trap. |
|