mirror of
https://github.com/Alfresco/alfresco-content-app.git
synced 2026-09-09 18:02:54 +00:00
[ACS-12451] Add missing upgrade guides in ACA (#5345)
* [ACS-12451] Add missing upgrade guides in ACA * [ACS-12451] CR fix
This commit is contained in:
Michal Kinas
@@ -0,0 +1,213 @@
|
||||
---
|
||||
Title: Upgrading from ACA v4.0 to v4.1
|
||||
---
|
||||
|
||||
# Upgrading from ACA v4.0 to v4.1
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.0.0 project to
|
||||
v4.1.0.
|
||||
|
||||
The headline of this release is the **ADF platform bump from 6.0.0 to 6.2.0** (and `@alfresco/js-api` 6.0.0 → 6.2.0).
|
||||
Because that spans **two** ADF releases, most of the required work in this upgrade is **adapting to the breaking
|
||||
changes ADF introduced in 6.1 and 6.2** — read those two ADF guides alongside this one:
|
||||
|
||||
- [ADF — Upgrading from v6.0 to v6.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade60-61.md)
|
||||
- [ADF — Upgrading from v6.1 to v6.2](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade61-62.md)
|
||||
|
||||
Angular is a patch bump only (`14.1.2` → `14.1.3`), but the **Node requirement moved to 18**. On the ACA side the
|
||||
most significant change is that three bundled extensions (**About**, **MS-Office/AOS**, **Folder Rules**) became
|
||||
**secondary entry points of `@alfresco/aca-content`**, changing their import paths. Read the
|
||||
[breaking changes](#breaking-changes) carefully.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps below
|
||||
involve code and configuration changes — commit or back up your work first.
|
||||
|
||||
**Node 18 is now required.** ACA's pinned Node version (`.nvmrc`) moved from **14** to **18**; move your build/CI
|
||||
to Node 18 before upgrading. (This matches the ADF 6.1 Node bump.)
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 6.1 / 6.2](#aligning-with-adf-61--62)
|
||||
- [ADF / js-api versions and caret ranges](#adf--js-api-versions-and-caret-ranges)
|
||||
- [Angular Flex-Layout removed](#angular-flex-layout-removed)
|
||||
- [Shared-link dialog is date-only](#shared-link-dialog-is-date-only)
|
||||
- [Advanced search widgets](#advanced-search-widgets)
|
||||
- [Theming — remove CSS variables that ADF now provides](#theming--remove-css-variables-that-adf-now-provides)
|
||||
- [Fonts are now published packages](#fonts-are-now-published-packages)
|
||||
- [Standalone components, `inject()` and view encapsulation](#standalone-components-inject-and-view-encapsulation)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Extensions moved to `aca-content` secondary entry points](#extensions-moved-to-aca-content-secondary-entry-points)
|
||||
- [AcaAboutModule no longer uses forRoot](#acaaboutmodule-no-longer-uses-forroot)
|
||||
- [aca-shared exports](#aca-shared-exports)
|
||||
- [Removed plugins and components](#removed-plugins-and-components)
|
||||
- [Changed automation ids](#changed-automation-ids)
|
||||
- [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": "6.2.0",
|
||||
"@alfresco/adf-content-services": "6.2.0",
|
||||
"@alfresco/adf-extensions": "6.2.0",
|
||||
"@alfresco/js-api": "6.2.0",
|
||||
"@angular/core": "14.1.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/adf-testing` move to `6.2.0` as well. Two vendored assets became real
|
||||
dependencies — `material-icons` (`^1.13.8`) and `@fontsource/open-sans` (`^5.0.3`) — and `@angular/flex-layout`
|
||||
was **removed** (see below). Clean `node_modules` and the lockfile, then reinstall on Node 18.
|
||||
|
||||
## Aligning with ADF 6.1 / 6.2
|
||||
|
||||
Most of this release is adapting ACA to the breaking changes ADF shipped across 6.1 and 6.2. Each item below links
|
||||
back to the ADF guide that describes the underlying change.
|
||||
|
||||
### ADF / js-api versions and caret ranges
|
||||
|
||||
`@alfresco/adf-*` and `@alfresco/js-api` moved from exact pins to **caret ranges** in the ACA libraries'
|
||||
`peerDependencies` (e.g. `>=6.0.0` / exact pin → `^6.1.0-0`), mirroring the ADF 6.1 change. If you maintain a fork
|
||||
with its own `package.json` pins, switch to caret ranges so a compatible `6.x` build resolves.
|
||||
(See ADF 6.1 → "`@alfresco/js-api` and ADF peers use a caret range".)
|
||||
|
||||
### Angular Flex-Layout removed
|
||||
|
||||
`@angular/flex-layout` was removed from ACA's `package.json` (root, `aca-shared`, `folder-rules`), following its
|
||||
removal from the ADF libraries. Any spec/code importing `CoreModule` from `@angular/flex-layout` was repointed to
|
||||
`@alfresco/adf-core`. If your fork used flex-layout only transitively via ADF/ACA, add it to your own
|
||||
`package.json`, or migrate those templates off `fxLayout`/`fxFlex`.
|
||||
(See ADF 6.1 → "Angular Flex-Layout removed".)
|
||||
|
||||
### Shared-link dialog is date-only
|
||||
|
||||
ADF 6.2 changed the share-link expiry control to a **date-only** picker and stopped reading the
|
||||
`sharedLinkDateTimePickerType` app-config key. ACA removed that key from `app.config.json` accordingly
|
||||
(`"sharedLinkDateTimePickerType": "datetime"` deleted from `app/src/app.config.json.tpl`). Remove it from any
|
||||
custom `app.config.json`.
|
||||
(See ADF 6.2 → "Share dialog: expiry is now date-only".)
|
||||
|
||||
### Advanced search widgets
|
||||
|
||||
ACA adopted the new ADF search widgets in `projects/aca-content/assets/app.extensions.json`:
|
||||
|
||||
- The **logical filter** (`"selector": "logical-filter"`) was wired into the search configuration.
|
||||
- The **Tags** and **Location** filters switched to the new `autocomplete-chips` widget (`field: "TAG"` with
|
||||
`allowOnlyPredefinedValues: true`; `field: "SITE"` with `options: ["_REPOSITORY_"]`).
|
||||
- Several **facets were converted to filters** using the new search-filter widget model, and unused i18n keys were
|
||||
dropped.
|
||||
|
||||
If you customised ACA's search configuration, reconcile it against the new `app.extensions.json` search block.
|
||||
(See ADF 6.1/6.2 → new `logical-filter` / `autocomplete-chips` search widgets.)
|
||||
|
||||
### Theming — remove CSS variables that ADF now provides
|
||||
|
||||
ADF 6.2 exposes component styling through `--adf-*` CSS custom properties. ACA deleted its redundant local
|
||||
`--theme-*` overrides that ADF now provides by default (in `adf-about.theme.scss`, `adf-pagination.theme.scss`
|
||||
and `variables.scss`). If your fork re-declared any of those `--theme-*` variables, drop them and theme through
|
||||
the ADF `--adf-*` properties instead.
|
||||
(See ADF 6.2 → theme changes / new `--adf-*` custom properties.)
|
||||
|
||||
### Fonts are now published packages
|
||||
|
||||
The vendored **Material Icons** and **Open Sans** fonts were removed from `app/src/assets/fonts/` and replaced by
|
||||
the published packages `material-icons` and `@fontsource/open-sans`, imported from `styles.scss`. `AppModule` now
|
||||
injects `MatIconRegistry` and calls `setDefaultFontSetClass('material-icons-outlined')`. If your fork vendored
|
||||
these fonts, switch to the packages.
|
||||
(See ADF 6.1 → material-icons externalised to the published package.)
|
||||
|
||||
### Standalone components, `inject()` and view encapsulation
|
||||
|
||||
Aligning with ADF 6.2's `inject()` refactor and standalone direction, ACA:
|
||||
|
||||
- flattened component/service constructors, removing now-unused injections (`Optimise injections and imports`);
|
||||
- migrated a number of modules/components to **standalone**;
|
||||
- enforced `ViewEncapsulation.None` across components via a new lint rule
|
||||
(`@alfresco/eslint-angular/use-none-component-view-encapsulation`) so `--adf-*` design tokens cascade correctly.
|
||||
|
||||
If you subclass ACA components or rely on their emulated encapsulation, re-check your styles.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Extensions moved to `aca-content` secondary entry points
|
||||
|
||||
The three bundled extensions are no longer separate packages — they are **secondary entry points of
|
||||
`@alfresco/aca-content`**. Update the imports in your `extensions.module.ts` (and `package.json`):
|
||||
|
||||
| Extension | Before (v4.0.0) | After (v4.1.0) |
|
||||
| --------------- | ----------------------------------- | ------------------------------------ |
|
||||
| Folder Rules | `@alfresco/aca-folder-rules` | `@alfresco/aca-content/folder-rules` |
|
||||
| MS-Office (AOS) | `@alfresco/adf-office-services-ext` | `@alfresco/aca-content/ms-office` |
|
||||
| About | `@alfresco/aca-about` | `@alfresco/aca-content/about` |
|
||||
|
||||
### AcaAboutModule no longer uses forRoot
|
||||
|
||||
`AcaAboutModule.forRoot(...)` was removed. Import the module directly and supply the former `forRoot` arguments
|
||||
through the new injection tokens `DEV_MODE_TOKEN` and `PACKAGE_JSON` (exported from `@alfresco/aca-content/about`):
|
||||
|
||||
```ts
|
||||
// Before (v4.0.0)
|
||||
import { AcaAboutModule } from '@alfresco/aca-about';
|
||||
// ...
|
||||
imports: [ AcaAboutModule.forRoot(environment.production, packageJson) ]
|
||||
|
||||
// After (v4.1.0)
|
||||
import { AcaAboutModule, DEV_MODE_TOKEN, PACKAGE_JSON } from '@alfresco/aca-content/about';
|
||||
// ...
|
||||
imports: [ AcaAboutModule ],
|
||||
providers: [
|
||||
{ provide: DEV_MODE_TOKEN, useValue: !environment.production },
|
||||
{ provide: PACKAGE_JSON, useValue: packageJson }
|
||||
]
|
||||
```
|
||||
|
||||
### aca-shared exports
|
||||
|
||||
`@alfresco/aca-shared` changed its public surface (standalone migration):
|
||||
|
||||
- **Removed** module exports: `LockedByModule`, `GenericErrorModule`, `SharedInfoDrawerModule`
|
||||
(`locked-by.module`, `generic-error.module`, `info-drawer/shared-info-drawer.module`). Import the now-standalone
|
||||
components directly instead of the modules.
|
||||
- **Added** exports: the new `OpenInAppComponent` / `OpenInAppModule` (`components/open-in-app`).
|
||||
|
||||
`@alfresco/aca-shared/rules` and `@alfresco/aca-shared/store` are unchanged.
|
||||
|
||||
### Removed plugins and components
|
||||
|
||||
- The internal plugin assets `app.debug.json`, `app.metadata.json` and `app.search.json` were removed, along with
|
||||
the `DocumentDisplayModeComponent` (and its toolbar entry). If you referenced these, remove the references.
|
||||
- The unused `create-menu` component was deleted.
|
||||
|
||||
### Changed automation ids
|
||||
|
||||
Some non-unique `data-automation-id`s were disambiguated — update any e2e selectors that relied on the old values:
|
||||
|
||||
- Toolbar menu item title `menu-item-title` split into `mat-button-menu-item-title` and
|
||||
`mat-flat-button-menu-item-title`.
|
||||
- The search button locator changed from `.app-search-button` to the scoped `aca-search-input .app-search-button`.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Open in App dialog** — a new `OpenInAppComponent` (`@alfresco/aca-shared`) prompts users to open content in the
|
||||
mobile app; shown after login and for private files.
|
||||
- **Multi-select** enabled for the Files and Trashcan views.
|
||||
- **User initials** displayed for the current user.
|
||||
- New **filter-state** styles and a facets-section UI refresh.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Navigation | Navigation behaviour was reworked to improve the user experience. |
|
||||
| Search input | Several search-input bugs were fixed. |
|
||||
| Performance | Template function calls were replaced with variable references (change-detection cost); the thumbnail column was optimised. |
|
||||
| Libraries | Library-details styles are no longer lost after refreshing the page. |
|
||||
| Security | An insecure-randomness issue was fixed. |
|
||||
Reference in New Issue
Block a user