mirror of
https://github.com/Alfresco/alfresco-content-app.git
synced 2026-09-09 18:02:54 +00:00
174 lines
9.8 KiB
Markdown
174 lines
9.8 KiB
Markdown
---
|
|
Title: Upgrading from ACA v4.4.1 to v5.0.1
|
|
---
|
|
|
|
# Upgrading from ACA v4.4.1 to v5.0.1
|
|
|
|
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.4.1 project to
|
|
v5.0.1 (covering the 5.0.0 and 5.0.1 releases).
|
|
|
|
**This is a major release.** The headline change is **Angular 14 → 15**, which brings the **Angular Material MDC
|
|
migration** — the single biggest source of visual breakage. It moves **ADF 6.7.1 → 7.0.0-alpha.2** and
|
|
**`@alfresco/js-api` 7.6.1 → 8.0.0-alpha.2**, and **TypeScript 4.7 → 4.9**. The ADF span crosses three ADF guides
|
|
(most relevant is the **7.0.0-alpha.2** section of the 6.9 → 7.0 guide, which is the Angular-15 + MDC step):
|
|
|
|
- [ADF — Upgrading from v6.7.1 to v6.8.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade671-68.md)
|
|
- [ADF — Upgrading from v6.8 to v6.9](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade68-69.md)
|
|
- [ADF — Upgrading from v6.9 to v7.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md) (see the **7.0.0-alpha.2** section)
|
|
|
|
Because of the MDC migration, budget time to re-audit any Material CSS overrides in your fork. Read the
|
|
[breaking changes](#breaking-changes) carefully.
|
|
|
|
> **rxjs / Nx note:** although ADF's 7.0.0-alpha.2 itself moved to rxjs 7.8 and a newer Nx, ACA's root manifest at
|
|
> 5.0.1 still pins **rxjs 6.6.6** and **Nx 17.3.1** (and zone.js 0.11.8), so those ADF implications do **not** apply
|
|
> to your ACA app at this version.
|
|
|
|
## Before you begin
|
|
|
|
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your
|
|
application to **Angular 15 / TypeScript 4.9** in lockstep. Node 18 (`.nvmrc`) is unchanged. Budget time to build,
|
|
re-theme (Material MDC) and re-test after upgrading.
|
|
|
|
## Contents
|
|
|
|
- [Library updates](#library-updates)
|
|
- [Aligning with Angular 15 / ADF 7.0-alpha](#aligning-with-angular-15--adf-70-alpha)
|
|
- [Angular Material MDC migration](#angular-material-mdc-migration)
|
|
- [ADF standalone components and MaterialModule](#adf-standalone-components-and-materialmodule)
|
|
- [ADF Notification Service](#adf-notification-service)
|
|
- [ADF document-list reload](#adf-document-list-reload)
|
|
- [js-api v8](#js-api-v8)
|
|
- [Breaking changes](#breaking-changes)
|
|
- [Library public API](#library-public-api)
|
|
- [Services and state rework](#services-and-state-rework)
|
|
- [Extension schema and configuration](#extension-schema-and-configuration)
|
|
- [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": {
|
|
"@angular/core": "15.2.10",
|
|
"@angular/material": "15.2.9",
|
|
"typescript": "4.9.5",
|
|
"@alfresco/adf-core": "7.0.0-alpha.2",
|
|
"@alfresco/adf-content-services": "7.0.0-alpha.2",
|
|
"@alfresco/adf-extensions": "7.0.0-alpha.2",
|
|
"@alfresco/js-api": "8.0.0-alpha.2"
|
|
}
|
|
}
|
|
```
|
|
|
|
`@alfresco/adf-cli` moves to `7.0.0-alpha.2` too. `rxjs` (`6.6.6`), `nx` (`17.3.1`), `zone.js` (`0.11.8`) and Node
|
|
(`.nvmrc` `18`) are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
|
|
|
## Aligning with Angular 15 / ADF 7.0-alpha
|
|
|
|
Most of this release is the Angular 15 platform move and adapting to ADF's 7.0.0-alpha.2 changes. See the ADF
|
|
[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md)
|
|
(7.0.0-alpha.2 section) for the underlying detail.
|
|
|
|
### Angular Material MDC migration
|
|
|
|
Angular 15's Material components were rewritten onto MDC, changing their internal DOM and CSS class names
|
|
(`.mat-*` → `.mat-mdc-*`). ACA's NG15 migration (ACS-6693) was followed by a wave of MDC-driven restyling and
|
|
layout fixes (toolbar buttons, create/upload buttons, `mat-tabs`, dialog paddings, search input, bulk-action
|
|
dropdown, badges, folder-rules dialogs). **If your fork styles Material internals — directly or by overriding ACA
|
|
component styles — you must re-audit those styles.** This is the biggest source of visual breakage in this upgrade.
|
|
|
|
### ADF standalone components and MaterialModule
|
|
|
|
ADF 7.0-alpha.2 makes most components standalone and deprecates the shared `MaterialModule`. ACA:
|
|
|
|
- updated document-list / column / context-menu / sidenav imports to the **standalone** ADF symbols (e.g. importing
|
|
`DynamicColumnComponent` / `DocumentListPresetRef` directly instead of `ExtensionsModule`);
|
|
- removed the deprecated shared **`MaterialModule`** from its imports.
|
|
|
|
If your fork imports ADF via NgModules or `MaterialModule`, import the standalone components / specific
|
|
`@angular/material/*` modules directly.
|
|
|
|
### ADF Notification Service
|
|
|
|
ACA now calls ADF's `NotificationService` directly for snackbars instead of dispatching NgRx snackbar actions
|
|
(reworked across the content-management / node-template services, search input, toggle-edit-offline,
|
|
toggle-join-library, and the library/template/upload/router effects). If you dispatched those ACA snackbar actions,
|
|
call the ADF service instead.
|
|
|
|
### ADF document-list reload
|
|
|
|
ACA switched its list-refresh plumbing to ADF's **`DocumentListService.reload()` / `reload$`** (a 7.0.0-alpha.2
|
|
addition), removing its own reload logic from `app-hook.service` and related effects/actions.
|
|
|
|
### js-api v8
|
|
|
|
`@alfresco/js-api` moved to `8.0.0-alpha.2`. ACA wired the linked js-api path into `tsconfig.adf.json` and raised
|
|
the ACA libraries' peer ranges accordingly. Update any pins to allow js-api 8.
|
|
|
|
## Breaking changes
|
|
|
|
### Library public API
|
|
|
|
The published ACA libraries changed their public surface:
|
|
|
|
**`@alfresco/aca-shared`:**
|
|
|
|
- **Renamed:** `aca-file-auto-download.service` → **`auto-download.service`** (`AcaFileAutoDownloadService` reworked
|
|
into `AutoDownloadService`).
|
|
- **Moved:** the `modal-configuration` model moved out of `@alfresco/aca-shared` to `@alfresco/aca-shared/store`.
|
|
- **Added:** `constants`, the `plugin-enabled.guard` (route guard), and the new `app-settings.service` /
|
|
`user-profile.service` (see [Services and state rework](#services-and-state-rework)).
|
|
|
|
**`@alfresco/aca-shared/store`:**
|
|
|
|
- **Removed `StoreModule`** (`store.module`) — effect registration was simplified; register effects via the app's
|
|
`app-store.module.ts` instead of importing the old module.
|
|
- **Removed** `dialog.effects` (dialog effects were removed) and the unused logout action.
|
|
- **Added** the relocated `modal-configuration` model.
|
|
|
|
**`@alfresco/aca-content/viewer`:** now also exports `PreviewComponent`.
|
|
|
|
### Services and state rework
|
|
|
|
Several concerns moved out of the NgRx store into root-provided services (migrate direct store/config reads):
|
|
|
|
- **`UserProfileService`** — holds the current user profile (`userProfile$`, `loadUserProfile()` via `PeopleApi` +
|
|
groups); replaces the profile slice of the app reducer.
|
|
- **`AppSettingsService`** — typed getters over `AppConfigService` (`appName`, `appVersion`, `appCopyright`,
|
|
`landingPage`, `aosHost`, `mimeTypes`, `appLogoUrl`, …). Roughly 800 lines were removed from `app.config.json`
|
|
and the corresponding store state; components now read settings from this service.
|
|
- **`AutoDownloadService`** — the renamed auto-download service now reads its size threshold from `AppSettingsService`.
|
|
|
|
### Extension schema and configuration
|
|
|
|
Update your `app.config.json` / `app.extensions.json` and any custom extensions:
|
|
|
|
- **`aca:fields` → `app:fields`** — the custom search-form field property was renamed (in `DEFAULT_SEARCH`,
|
|
`DUBLIN_CORE`, `EFFECTIVITY`). Rename it in any custom search configuration.
|
|
- **`extension.schema.json` review** — the `userActions` and `mainAction` feature definitions (and a duplicate
|
|
top-level `badges`) were removed / relocated. Extensions relying on those schema keys must be updated.
|
|
- **Blank-page route removed** — the `blank` route was removed from `app.routes.ts` and `app.config.json`.
|
|
- **Plugin routing guard** — routes for optional plugins are now gated by a new `plugin-enabled.guard` (exported
|
|
from `@alfresco/aca-shared`).
|
|
|
|
## New components and features
|
|
|
|
- **Manage Holds / bulk Legal Hold** — a new *Manage Holds* dialog with Apply-New-Hold / Manage-Existing-Holds
|
|
tabs for bulk operations, backed by new `bulk-actions-dropdown` and `datatable-cell-badges` components and new
|
|
`bulk-actions` / badge-`tooltip` entries in `extension.schema.json` (aligns with ADF 7.0's Legal Hold area).
|
|
- **Security marks for Folder Rules** — rule actions can set security marks.
|
|
- **HxI connector availability** — a new store selector reports whether the HxI connector is available.
|
|
|
|
## Behavioural changes
|
|
|
|
| Area | Change |
|
|
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Multi-select | Multi-selection is now **on by default** across the document lists (files, favorites, libraries, recent-files, shared-files, search-results, trashcan). |
|
|
| Search results | Delete and move actions are now available on the search-results page. |
|
|
| Folder rules | Rule-action node selection changed from multiple to **single**. |
|
|
| Checkboxes | Selection checkboxes use the Hyland-blue checked state. |
|
|
| Testing (fork note) | Protractor e2e was removed (migration to Playwright is complete); if your fork extends ACA's Protractor harness, move to Playwright. |
|