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
+17
-2
@@ -35,12 +35,27 @@
|
||||
- [Tutorials](/tutorials/)
|
||||
- [Custom route with parameters](/tutorials/custom-route-with-parameters)
|
||||
- [Dialog actions](/tutorials/dialog-actions)
|
||||
- [Custom route with parameters](tutorials/custom-route-with-parameters)
|
||||
- [How to create your first extension](/tutorials/how-to-create-your-first-extension)
|
||||
- [How to extend Content Metadata](/tutorials/content-metadata)
|
||||
- [How to extend File lists](/tutorials/file-lists)
|
||||
- [How to extend File Preview](/tutorials/file-preview)
|
||||
- [How to extend The Search Form](/tutorials/search-form)
|
||||
- [Upgrade guide](/upgrade-guide/)
|
||||
- [Upgrade from v2.4.0 to v2.5.0](/upgrade-guide/upgrade24-45)
|
||||
- [Upgrade from v2.4.0 to v2.5.0](/upgrade-guide/upgrade24-45)
|
||||
- [Upgrade from v4.0.0 to v4.1.0](/upgrade-guide/upgrade40-41)
|
||||
- [Upgrade from v4.1.0 to v4.2.0](/upgrade-guide/upgrade41-42)
|
||||
- [Upgrade from v4.2.0 to v4.3.0](/upgrade-guide/upgrade42-43)
|
||||
- [Upgrade from v4.3.0 to v4.4.1](/upgrade-guide/upgrade43-441)
|
||||
- [Upgrade from v4.4.1 to v5.0.1](/upgrade-guide/upgrade441-501)
|
||||
- [Upgrade from v5.0.1 to v5.1.1](/upgrade-guide/upgrade501-511)
|
||||
- [Upgrade from v5.1.1 to v5.2.0](/upgrade-guide/upgrade511-520)
|
||||
- [Upgrade from v5.2.0 to v5.3.0](/upgrade-guide/upgrade520-530)
|
||||
- [Upgrade from v5.3.0 to v6.0.0](/upgrade-guide/upgrade530-600)
|
||||
- [Upgrade from v6.0.0 to v7.0.1](/upgrade-guide/upgrade600-701)
|
||||
- [Upgrade from v7.0.1 to v7.1.0](/upgrade-guide/upgrade701-710)
|
||||
- [Upgrade from v7.1.0 to v7.2.0](/upgrade-guide/upgrade710-720)
|
||||
- [Upgrade from v7.2.0 to v7.3.0](/upgrade-guide/upgrade720-730)
|
||||
- [Upgrade from v7.3.0 to v7.4.1](/upgrade-guide/upgrade730-741)
|
||||
- [Upgrade from v7.4.1 to v7.5.0](/upgrade-guide/upgrade741-750)
|
||||
- [Upgrade from v7.5.0 to v8.0.0](/upgrade-guide/upgrade750-800)
|
||||
- [Get help](/help)
|
||||
|
||||
@@ -9,4 +9,20 @@ Below are links to the upgrade guides notes for released versions
|
||||
|
||||
## Contents
|
||||
|
||||
- [Upgrade from v2.4.o to v2.5.0](/upgrade-guide/upgrade24-45)
|
||||
- [Upgrade from v7.5.0 to v8.0.0](upgrade750-800.md)
|
||||
- [Upgrade from v7.4.1 to v7.5.0](upgrade741-750.md)
|
||||
- [Upgrade from v7.3.0 to v7.4.1](upgrade730-741.md)
|
||||
- [Upgrade from v7.2.0 to v7.3.0](upgrade720-730.md)
|
||||
- [Upgrade from v7.1.0 to v7.2.0](upgrade710-720.md)
|
||||
- [Upgrade from v7.0.1 to v7.1.0](upgrade701-710.md)
|
||||
- [Upgrade from v6.0.0 to v7.0.1](upgrade600-701.md)
|
||||
- [Upgrade from v5.3.0 to v6.0.0](upgrade530-600.md)
|
||||
- [Upgrade from v5.2.0 to v5.3.0](upgrade520-530.md)
|
||||
- [Upgrade from v5.1.1 to v5.2.0](upgrade511-520.md)
|
||||
- [Upgrade from v5.0.1 to v5.1.1](upgrade501-511.md)
|
||||
- [Upgrade from v4.4.1 to v5.0.1](upgrade441-501.md)
|
||||
- [Upgrade from v4.3.0 to v4.4.1](upgrade43-441.md)
|
||||
- [Upgrade from v4.2.0 to v4.3.0](upgrade42-43.md)
|
||||
- [Upgrade from v4.1.0 to v4.2.0](upgrade41-42.md)
|
||||
- [Upgrade from v4.0.0 to v4.1.0](upgrade40-41.md)
|
||||
- [Upgrade from v2.4.0 to v2.5.0](upgrade24-45.md)
|
||||
|
||||
@@ -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. |
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
Title: Upgrading from ACA v4.1 to v4.2
|
||||
---
|
||||
|
||||
# Upgrading from ACA v4.1 to v4.2
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.1.0 project to
|
||||
v4.2.0.
|
||||
|
||||
The headline of this release is the **ADF 6.2.0 → 6.3.0** bump and, with it, the **`@alfresco/js-api` 6.2.0 → 7.0.0
|
||||
(major)** upgrade. The bulk of the work is **adapting to the ADF 6.3 / js-api v7 breaking changes** — read the ADF
|
||||
guide alongside this one:
|
||||
|
||||
- [ADF — Upgrading from v6.2 to v6.3](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade62-63.md)
|
||||
|
||||
## 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 still required (unchanged
|
||||
from 4.1.0).
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 6.3 / js-api v7](#aligning-with-adf-63--js-api-v7)
|
||||
- [js-api v7 type migration](#js-api-v7-type-migration)
|
||||
- [Compatibility mode removed](#compatibility-mode-removed)
|
||||
- [Advanced search widgets](#advanced-search-widgets)
|
||||
- [Content metadata editable binding](#content-metadata-editable-binding)
|
||||
- [Breadcrumbs replaced by page headings](#breadcrumbs-replaced-by-page-headings)
|
||||
- [i18n resources moved to ADF](#i18n-resources-moved-to-adf)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Viewer and preview moved to aca-content entry points](#viewer-and-preview-moved-to-aca-content-entry-points)
|
||||
- [aca-shared exports](#aca-shared-exports)
|
||||
- [Docker and environment-variable overhaul](#docker-and-environment-variable-overhaul)
|
||||
- [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.3.0",
|
||||
"@alfresco/adf-content-services": "6.3.0",
|
||||
"@alfresco/adf-extensions": "6.3.0",
|
||||
"@alfresco/js-api": "7.0.0",
|
||||
"@angular/material-date-fns-adapter": "14.1.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/adf-testing` move to `6.3.0` as well. A new dependency,
|
||||
`@angular/material-date-fns-adapter`, is required by ADF's date-fns-based advanced date-range search widget.
|
||||
Angular (`14.1.3`), TypeScript (`4.7.4`), rxjs (`6.6.6`) and Node (`.nvmrc` `18`) are unchanged. Clean
|
||||
`node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 6.3 / js-api v7
|
||||
|
||||
Most of this release adapts ACA to the ADF 6.3 breaking changes — driven largely by the `@alfresco/js-api` v7
|
||||
major. See the [ADF 6.2 → 6.3 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade62-63.md)
|
||||
for the underlying details.
|
||||
|
||||
### js-api v7 type migration
|
||||
|
||||
js-api v7 renamed its model types, and ACA migrated to them app-wide (across `aca-content` and `aca-shared`):
|
||||
|
||||
| Before (js-api v6) | After (js-api v7) |
|
||||
| ------------------------ | -------------------- |
|
||||
| `MinimalNodeEntity` | `NodeEntry` |
|
||||
| `MinimalNodeEntryEntity` | `Node` |
|
||||
| `PathElementEntity` | `PathElement` |
|
||||
| `SiteBody` | `SiteBodyCreate` |
|
||||
| `FavoriteBody` | `FavoriteBodyCreate` |
|
||||
|
||||
This changes some **public** ACA surfaces, so extension authors must adapt:
|
||||
|
||||
- **NgRx action payloads** (`@alfresco/aca-shared/store`, `node.actions.ts`) — copy/move/delete/share/favorite
|
||||
action types changed from `MinimalNodeEntity[]` / `MinimalNodeEntity` to `NodeEntry[]` / `NodeEntry`.
|
||||
- **`ContentApiService`** (`@alfresco/aca-shared`) method signatures — e.g. `getNode()` / `restoreNode()` now
|
||||
return `Observable<NodeEntry>`, `unlockNode()` returns `Promise<NodeEntry>`, `addFavorite()` / `removeFavorite()`
|
||||
take `Array<NodeEntry>`, and `updateLibrary(siteId, siteBody: SiteBodyCreate)`.
|
||||
|
||||
Update your own type references accordingly. (See ADF 6.3 → "JS-API v7 and type migrations".)
|
||||
|
||||
### Compatibility mode removed
|
||||
|
||||
`AlfrescoApiCompatibility` was removed in js-api v7; ACA dropped its use (test utilities now use `AlfrescoApi` /
|
||||
`NodesApi` / `UploadApi` directly, and the Playwright/API wrappers were refactored onto the v7 model classes, e.g.
|
||||
`Site.VisibilityEnum.PUBLIC`). If your code referenced `AlfrescoApiCompatibility`, migrate to `AlfrescoApi`.
|
||||
(See ADF 6.3 → "Removed and hidden items".)
|
||||
|
||||
### Advanced search widgets
|
||||
|
||||
ACA adopted the ADF 6.3 advanced-search widgets in `projects/aca-content/assets/app.extensions.json` /
|
||||
`app/src/app.config.json`:
|
||||
|
||||
- **Created & Modified date filters merged** into one `date-range-advanced` widget (id `createdModifiedDateRange`,
|
||||
`field: "cm:created,cm:modified"`); the date format token changed `DD-MMM-YY` → **`dd-MMM-yy`** (moment →
|
||||
date-fns).
|
||||
- The size / file-type facets were replaced by the new **`properties`** widget (`field: "content.size,cm:name"`).
|
||||
- The **SITE** and **Categories** facets switched to the `autocomplete-chips` widget using the new
|
||||
**`autocompleteOptions`** object model (`[{ "value": "_REPOSITORY_" }]`) instead of plain string `options`.
|
||||
- New styles for the tabbed facet component (`.adf-search-filter-chip-tabbed`).
|
||||
|
||||
If you customised the search configuration, reconcile it against the new `app.extensions.json`. (See ADF 6.3 →
|
||||
"Advanced search" and "Search API changes".)
|
||||
|
||||
### Content metadata editable binding
|
||||
|
||||
The metadata tab now uses ADF 6.3's two-way `[(editable)]` binding on `adf-content-metadata-card`, and resets the
|
||||
editable state to `false` when a node is locked (reacting to the `EditOffline` store action). If you extend the
|
||||
metadata tab, adopt the two-way binding.
|
||||
|
||||
### Breadcrumbs replaced by page headings
|
||||
|
||||
Following ADF's breadcrumb rework (breadcrumbs moved to the `@alfresco/adf-core/breadcrumbs` secondary entry
|
||||
point), ACA **replaced the `<adf-breadcrumb>` on its list pages with an `<h1 class="aca-page-title">` heading**
|
||||
(favorites, libraries, recent-files, shared-files, trashcan, details, etc.). Any code or test targeting the
|
||||
`adf-breadcrumb` selector on those pages must be updated.
|
||||
|
||||
### i18n resources moved to ADF
|
||||
|
||||
The join-library message keys (`APP.MESSAGES.ERRORS.JOIN_REQUEST_FAILED` / `JOIN_CANCEL_FAILED` /
|
||||
`INVALID_SENDER_EMAIL` / `INVALID_RECEIVER_EMAIL`, and `JOINED` / `JOIN_REQUESTED` / `JOIN_CANCELED`) were removed
|
||||
from ACA's locale files — they are now provided by ADF 6.3. If you overrode these keys, re-source them from ADF.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Viewer and preview moved to aca-content entry points
|
||||
|
||||
The standalone `@alfresco/aca-viewer` and `@alfresco/aca-preview` packages were removed and became **secondary
|
||||
entry points of `@alfresco/aca-content`**. The exported symbols are unchanged — only the import path:
|
||||
|
||||
| Package | Before (v4.1.0) | After (v4.2.0) |
|
||||
| ------- | ----------------------- | ------------------------------- |
|
||||
| Viewer | `@alfresco/aca-viewer` | `@alfresco/aca-content/viewer` |
|
||||
| Preview | `@alfresco/aca-preview` | `@alfresco/aca-content/preview` |
|
||||
|
||||
### aca-shared exports
|
||||
|
||||
The standalone-component migration reshaped `@alfresco/aca-shared`'s public surface:
|
||||
|
||||
- **Toolbar components moved** from `.../components/tool-bar/...` to `.../components/toolbar/...` — deep imports
|
||||
into the old `tool-bar` path break (the package-root exports still resolve, only the deep path changed).
|
||||
- **Removed exports:** `OpenInAppModule` (the `OpenInAppComponent` is still exported — import the standalone
|
||||
component), and `AlfrescoOfficeExtensionService` (plugin handling moved into the rules engine).
|
||||
- `SharedModule` and `SharedToolbarModule` were moved under `aca-shared/src/lib/deprecated/` and marked
|
||||
`@deprecated` backward-compat shims — import the standalone components/directives directly.
|
||||
|
||||
### Docker and environment-variable overhaul
|
||||
|
||||
The ACA Docker image was reworked (epic `ACA-4715`). If you run the published image or build your own, note:
|
||||
|
||||
- **`envsubst` templating was removed.** `app/src/app.config.json.tpl` was renamed to `app.config.json` with ADF
|
||||
runtime tokens (`{protocol}//{hostname}{:port}`) and hard-coded defaults; a new entrypoint
|
||||
(`docker/docker-entrypoint.d/30-sed-on-appconfig.sh`) patches a **curated set of ~14 runtime env vars** via `sed`.
|
||||
- **Env vars that are no longer applied at runtime** (plugin toggles, viewer / download-prompt, mobile-app-switch,
|
||||
session-timeout, etc.) now use fixed defaults and are **silently ignored** if passed — set them in your own
|
||||
`app.config.json` instead.
|
||||
- The `--build-arg PROJECT_NAME` was removed (the image is wired to `dist/content-ce`), and the
|
||||
`envsub` / `assemble-app-config` / `prebuild` / `prestart` / `validate-app-config` npm scripts were deleted.
|
||||
|
||||
See the new `docs/getting-started/docker.md` for the current setup.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Standalone components** — a large migration converted the `aca-shared` component library to Angular standalone
|
||||
(dropping most `CoreModule` usage); this is the source of the module-export removals above.
|
||||
- **Improved plugin handling** — plugin enable/disable moved into the rules engine (`app.rules.ts`); the About
|
||||
dialog's plugins section was fixed.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| File lists | Row checkboxes are hidden by default in the Files and Trashcan lists (`[multiselect]="false"`; selection mode stays `multiple`). |
|
||||
| Document list | The filter header is now retained when query params are present. |
|
||||
| Security marks | The files document-list preset is now reactive (`filesDocumentListPreset$`), fixing incorrect initial loading of security-marks columns. |
|
||||
| Styling | `!important` was removed from ACA style overrides (lint-enforced) — re-check custom styles that relied on the old cascade. |
|
||||
| Security | Incomplete string-escaping in toolbar selectors was hardened (regex escaping). |
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
Title: Upgrading from ACA v4.2 to v4.3
|
||||
---
|
||||
|
||||
# Upgrading from ACA v4.2 to v4.3
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.2.0 project to
|
||||
v4.3.0.
|
||||
|
||||
This is a smaller release built on **ADF 6.3.0 → 6.4.0** (`@alfresco/js-api` 7.0.0 → 7.1.0, a minor bump). The main
|
||||
ADF-driven change is completing the **moment → date-fns** move (ADF 6.4 dropped `moment`), and ACA **adopts several
|
||||
new ADF 6.4 capabilities** (configurable document-list columns, custom metadata panels). Read the ADF guide
|
||||
alongside this one:
|
||||
|
||||
- [ADF — Upgrading from v6.3 to v6.4](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade63-64.md)
|
||||
|
||||
Angular, Material, TypeScript, rxjs and the Node version are all **unchanged**. ACA's public library API
|
||||
(`@alfresco/aca-shared` / `@alfresco/aca-content` entry points) is unchanged too — no exports were removed or
|
||||
renamed — so most of this upgrade is dependency/config, not code. Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18 is still
|
||||
required (unchanged).
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 6.4](#aligning-with-adf-64)
|
||||
- [moment removed (date-fns completion)](#moment-removed-date-fns-completion)
|
||||
- [Configurable document-list columns](#configurable-document-list-columns)
|
||||
- [Custom metadata side panels](#custom-metadata-side-panels)
|
||||
- [Folder-rules category autocomplete](#folder-rules-category-autocomplete)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Nx 16 workspace migration](#nx-16-workspace-migration)
|
||||
- [Peer dependency ranges loosened](#peer-dependency-ranges-loosened)
|
||||
- [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.4.0",
|
||||
"@alfresco/adf-content-services": "6.4.0",
|
||||
"@alfresco/adf-extensions": "6.4.0",
|
||||
"@alfresco/js-api": "7.1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/adf-testing` move to `6.4.0` as well. Four **`moment`-related dependencies were
|
||||
removed** — `moment`, `moment-es6`, `@angular/material-moment-adapter` and `@mat-datetimepicker/moment` — while
|
||||
`@angular/material-date-fns-adapter`, `date-fns` and `@mat-datetimepicker/core` are retained. Angular (`14.1.3`),
|
||||
TypeScript (`4.7.4`), rxjs (`6.6.6`) and Node (`.nvmrc` `18`) are unchanged. Clean `node_modules` and the lockfile,
|
||||
then reinstall.
|
||||
|
||||
## Aligning with ADF 6.4
|
||||
|
||||
See the [ADF 6.3 → 6.4 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade63-64.md)
|
||||
for the underlying changes.
|
||||
|
||||
### moment removed (date-fns completion)
|
||||
|
||||
ADF 6.4 completed its moment → date-fns migration and dropped `moment` as a runtime/peer dependency. ACA followed
|
||||
suit and removed the `moment` family from `package.json` (see [Library updates](#library-updates)). ACA's own
|
||||
library/component source was already date-fns-based, so the only code change was in e2e tests, which now format
|
||||
dates through ADF's `DateFnsUtils.formatDate()` (from `@alfresco/adf-core`) instead of raw `date-fns`. If your fork
|
||||
still imports `moment` (or the moment Material adapters) transitively via ACA/ADF, add them to your own
|
||||
`package.json` or migrate to date-fns. (See ADF 6.4 → "Date handling (moment → date-fns)".)
|
||||
|
||||
### Configurable document-list columns
|
||||
|
||||
Adopting ADF 6.4's `DataColumn.isHidden` support, ACA added an `[isHidden]="column.isHidden"` binding to the
|
||||
`data-column` definitions across its seven document lists (`files`, `favorites`, `favorite-libraries`,
|
||||
`libraries`, `recent-files`, `shared-files`, `trashcan`), so columns can be shown/hidden. If you customise these
|
||||
lists, carry the `isHidden` binding through.
|
||||
|
||||
### Custom metadata side panels
|
||||
|
||||
ACA adopts ADF 6.4's `ContentMetadataComponent` `@Input() customPanels` to let extensions contribute extra metadata
|
||||
panels. This adds a new extension point (see [New components and features](#new-components-and-features)); the
|
||||
metadata tab now binds `[customPanels]` on `adf-content-metadata-card`.
|
||||
|
||||
### Folder-rules category autocomplete
|
||||
|
||||
The Folder Rules "Has Category" condition gained an autocomplete backed by ADF's `CategoryService.searchCategories()`
|
||||
(`@alfresco/adf-content-services`). Internally this added an `'auto-complete'` `RuleConditionFieldType`.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
ACA's published library API is unchanged in this release (the `public-api.ts` of every `@alfresco/aca-shared` and
|
||||
`@alfresco/aca-content` entry point is identical between 4.2.0 and 4.3.0 — no exports removed, renamed or newly
|
||||
deprecated). The consumer-affecting changes are at the dependency/build level:
|
||||
|
||||
### Nx 16 workspace migration
|
||||
|
||||
The workspace moved to **Nx 16** and the Nx package scope was renamed **`@nrwl/*` → `@nx/*`** (`nx` / `@nx/angular`
|
||||
/ `@nx/workspace` / `@nx/eslint-plugin` `16.10.0`). `nx.json`, `project.json`, `.eslintrc.json` and `tsconfig.json`
|
||||
were rewritten accordingly. If you maintain a fork with custom Nx targets or `@nrwl/*` imports, migrate them to
|
||||
`@nx/*` and run the Nx 16 migrations.
|
||||
|
||||
### Peer dependency ranges loosened
|
||||
|
||||
The published ACA libraries (`projects/aca-content`, `projects/aca-shared`) changed their `peerDependencies` from
|
||||
caret ranges to `>=` (e.g. `@alfresco/adf-core` `^6.3.0` → `>=6.4.0`, `@alfresco/js-api` `>=7.0.0` → `>=7.1.0`, and
|
||||
the `@angular/*` / `@ngx-translate/core` / `rxjs` / `zone.js` peers likewise). This mainly affects how versions
|
||||
resolve when you install those packages.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Name-column badges** — extensions can add icon badges (with tooltip, and an optional custom component) to the
|
||||
document-list name column. New public `Badge` interface (`@alfresco/aca-shared`, `extends ContentActionRef` with
|
||||
a `tooltip`), a new `features.badges` block in `app.extensions.json` (a `badge` needs `id`, `icon`, `tooltip`,
|
||||
optional `component`), and a new `AppExtensionService.getBadges(node)` method.
|
||||
- **Custom metadata side panels** — a new `features.customMetadataPanels` extension feature (array of
|
||||
`contentActionRef`) renders registered extension components as extra metadata panels, surfaced via the new
|
||||
`AppExtensionService.getCustomMetadataPanels(node)` method.
|
||||
- **Configurable document-list columns** — see [Configurable document-list columns](#configurable-document-list-columns).
|
||||
- **Breadcrumb navigation on the Details tab** — the Details page breadcrumb now navigates
|
||||
(`onBreadcrumbNavigate(path)` dispatching `NavigateToFolder`).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Info drawer | The info drawer / Details tab now opens **over a custom file preview** — `PageComponent.infoDrawerOpened$` no longer suppresses the drawer while a viewer outlet is active. |
|
||||
| Library metadata | The library-metadata info-drawer was reworked into a single reactive form; update/cancel now reflect immediately in the UI, and renaming a library to a whitespace-only name is prevented. |
|
||||
| Edit offline | Toggling "edit offline" now reselects the node so dependent UI refreshes. |
|
||||
| Icons | Toolbar/info-drawer icons and button pressed/focus states were updated to match the current design (e.g. the info-drawer toggle icon `menu_open` → `view_sidebar`). |
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
Title: Upgrading from ACA v4.3 to v4.4.1
|
||||
---
|
||||
|
||||
# Upgrading from ACA v4.3 to v4.4.1
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.3.0 project to
|
||||
v4.4.1 (covering the 4.4.0 and 4.4.1 releases).
|
||||
|
||||
This is a large release: it moves **ADF 6.4.0 → 6.7.1** (spanning several ADF releases) and `@alfresco/js-api`
|
||||
7.1.0 → 7.6.1, so most of the work is **adapting to the ADF breaking changes across 6.5.2, 6.6.0 and 6.7.x**. Read
|
||||
those ADF guides alongside this one:
|
||||
|
||||
- [ADF — Upgrading from v6.4 to v6.5.2](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade64-652.md)
|
||||
- [ADF — Upgrading from v6.5.2 to v6.6.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade652-66.md)
|
||||
- [ADF — Upgrading from v6.6.0 to v6.7.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade66-671.md)
|
||||
|
||||
Angular, Material, TypeScript, rxjs and the Node version are all **unchanged**; the build tooling moves to
|
||||
**Nx 17**. ACA's published library API (`@alfresco/aca-shared` / `@alfresco/aca-content` entry points) is
|
||||
unchanged — no exports removed or renamed — so the consumer-facing work is mostly **`app.config.json` /
|
||||
`app.extensions.json` configuration** plus adopting new ADF capabilities. Read the
|
||||
[breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18 is still
|
||||
required (unchanged). The steps below involve configuration changes — commit or back up your work first.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 6.5 / 6.6 / 6.7](#aligning-with-adf-65--66--67)
|
||||
- [Authentication — PKCE / code flow](#authentication--pkce--code-flow)
|
||||
- [Search — Elasticsearch, date range and highlighting](#search--elasticsearch-date-range-and-highlighting)
|
||||
- [Content metadata read-only model](#content-metadata-read-only-model)
|
||||
- [Viewer close-button position](#viewer-close-button-position)
|
||||
- [Document-list resizing, persistence and drag-drop columns](#document-list-resizing-persistence-and-drag-drop-columns)
|
||||
- [Theming](#theming)
|
||||
- [Disabling tags and categories](#disabling-tags-and-categories)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Configuration changes](#configuration-changes)
|
||||
- [Nx 17 workspace migration](#nx-17-workspace-migration)
|
||||
- [adf-testing dependency dropped](#adf-testing-dependency-dropped)
|
||||
- [E2E selector changes](#e2e-selector-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": "6.7.1",
|
||||
"@alfresco/adf-content-services": "6.7.1",
|
||||
"@alfresco/adf-extensions": "6.7.1",
|
||||
"@alfresco/js-api": "7.6.1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` moves to `6.7.1`; **`@alfresco/adf-testing` was removed** as a dependency. (4.4.0 shipped ADF
|
||||
`6.7.0` / js-api `7.6.0`; the 4.4.1 patch bumps them to `6.7.1` / `7.6.1`.) The build tooling
|
||||
moved to **Nx 17** (`@nx/*` / `nx` `17.x`, from `16.10.0`). Angular (`14.1.3`), TypeScript (`4.7.4`), rxjs
|
||||
(`6.6.6`) and Node (`.nvmrc` `18`) are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 6.5 / 6.6 / 6.7
|
||||
|
||||
Most of this release adapts ACA to the ADF breaking changes across three releases. Each item links back to the ADF
|
||||
guide that describes the underlying change.
|
||||
|
||||
### Authentication — PKCE / code flow
|
||||
|
||||
ACA switched its default OAuth2 flow to **PKCE authorization-code flow**: in `app.config.json`, `implicitFlow: true` became `implicitFlow: false` + **`codeFlow: true`** (and a new
|
||||
`APP_CONFIG_OAUTH2_CODE_FLOW` Docker env var).
|
||||
If your `app.config.json` pins `oauth2.implicitFlow`, review it against the new default. (See ADF 6.6 →
|
||||
"Authentication and SSO renames".)
|
||||
|
||||
### Search — Elasticsearch, date range and highlighting
|
||||
|
||||
- **Elasticsearch query migration** — the search configuration in `app.extensions.json` was updated for the
|
||||
Elasticsearch backend (e.g. `-PNAME:'0/wiki'` → `-PATH:'//cm:wiki/*'`, and autocomplete options gained a
|
||||
`query`). (See ADF 6.5.2 → "Search query migration (Elasticsearch)".)
|
||||
- **Date-range widget** — every `"selector": "date-range-advanced"` reverted to **`"date-range"`** (now the tabbed
|
||||
advanced widget), the date-format token changed `DD-MMM-YY` → **`dd-MMM-yy`**, and `displayedLabelsByField` maps
|
||||
were added. (See ADF 6.6 → "Search date-range widget replaced".)
|
||||
- **Search highlighting** — ACA now renders ADF search `highlight` snippets (config added under the results row).
|
||||
|
||||
If you customised the search configuration, reconcile it against the new `app.extensions.json`.
|
||||
|
||||
### Content metadata read-only model
|
||||
|
||||
Following ADF's content-metadata rework, ACA's metadata tab adopted the **`readOnly`** model (the previous
|
||||
`editable` input was inverted to `readOnly` with the opposite meaning) and re-wires the displayed aspect through
|
||||
the store. If you extend the metadata tab, migrate `editable` usage to `readOnly`. (See ADF 6.6 → "Content
|
||||
metadata property panels".)
|
||||
|
||||
### Viewer close-button position
|
||||
|
||||
The viewer close button's position is now configurable via `viewer.closeButtonPosition` in `app.config.json`
|
||||
(default `right`), adopting ADF 6.6's `CloseButtonPosition`. (See ADF 6.6 → "Viewer close button".)
|
||||
|
||||
### Document-list resizing, persistence and drag-drop columns
|
||||
|
||||
ACA adopted the ADF document-list column capabilities added across 6.5.2–6.7.x:
|
||||
|
||||
- **Resizable lists** — all document lists set `[isResizingEnabled]="true"` and `[blurOnResize]="false"`.
|
||||
- **Per-column opt-out** — columns are resizable by default in newer ADF, so ACA marks the thumbnail/icon columns
|
||||
`"resizable": false` (new `resizable` field in `extension.schema.json`).
|
||||
- **Persistence & drag-drop** — column size / visibility / order are persisted (via ADF's
|
||||
`setColumns*` inputs and `columns*Changed` outputs) and columns can be reordered by drag-drop
|
||||
(`"draggable": true`). Stable `id="app.*"` values were added to every `data-column`.
|
||||
|
||||
### Theming
|
||||
|
||||
- **Internal Angular Material CSS classes** — ACA removed most `.mat-*` / `.cdk-*` selector overrides in favour of
|
||||
ACA-owned `aca-*` / `adf-*` classes (preparation for ADF's Material MDC migration). If your fork overrides ACA
|
||||
styles via Material internals, re-audit them.
|
||||
- **Theme reference variables** — hardcoded/removed theme references were replaced with dynamic `--theme-*` tokens
|
||||
(e.g. `--theme-secondary-text`, `--theme-card-background-color`, `--theme-sidenav-active-text-color`). (See ADF
|
||||
6.6 → "Theme reference variables".)
|
||||
|
||||
### Disabling tags and categories
|
||||
|
||||
ACA can now disable the tags and categories features via `app.config.json` (default `true`), using ADF's
|
||||
`TagService.areTagsEnabled()` / `CategoryService.areCategoriesEnabled()`.
|
||||
|
||||
> **Config-key rename in 4.4.1:** the ACA keys were introduced in 4.4.0 as `plugins.tags` / `plugins.categories`,
|
||||
> then **renamed in 4.4.1 to `plugins.tagsEnabled` / `plugins.categoriesEnabled`** (ACS-6924) to avoid a naming
|
||||
> conflict with ADF's own plugin keys. Use the new `*Enabled` names in a custom `app.config.json` (or via the
|
||||
> `APP_CONFIG_PLUGIN_TAGS` / `APP_CONFIG_PLUGIN_CATEGORIES` env vars) — the ACA rule functions
|
||||
> `areTagsEnabled` / `areCategoriesEnabled` read the renamed keys.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
ACA's published library API is unchanged in this release — the `public-api.ts` of every `@alfresco/aca-shared` and
|
||||
`@alfresco/aca-content` entry point is byte-identical between 4.3.0 and 4.4.0 (no exports removed, renamed or newly
|
||||
deprecated). The breaking changes are at the configuration, build and dependency level.
|
||||
|
||||
### Configuration changes
|
||||
|
||||
Update your `app.config.json` / `app.extensions.json` (and any custom extensions):
|
||||
|
||||
- `oauth2.implicitFlow: true` → `implicitFlow: false` + `codeFlow: true` (PKCE).
|
||||
- The `date-range-advanced` search selector was removed — use `date-range`.
|
||||
- Viewer extensions are now keyed under an **`extensions`** block (by `fileExtension`) instead of the old `content`
|
||||
key in `app.extensions.json`.
|
||||
|
||||
### Nx 17 workspace migration
|
||||
|
||||
The workspace moved to **Nx 17** (`@nx/*` / `nx` `17.x`). `nx.json` and the cache configuration were rewritten. If
|
||||
you maintain a fork with custom Nx targets, run the Nx 17 migrations.
|
||||
|
||||
### adf-testing dependency dropped
|
||||
|
||||
`@alfresco/adf-testing` was removed from ACA's dependencies. If your tests imported it via ACA, add it to your own
|
||||
`devDependencies`.
|
||||
|
||||
### E2E selector changes
|
||||
|
||||
The viewer close-button e2e locator changed from `button[data-automation-id="adf-toolbar-back"]` to
|
||||
`button.adf-viewer-close-button` (following ADF's `adf-toolbar-back` → `adf-toolbar-left-back` id change). Update
|
||||
any e2e selectors targeting the old value.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Search highlighting** — matched terms in search results are highlighted (`aca-highlight`), configurable via
|
||||
the results row `highlight` settings.
|
||||
- **Configurable / persistent / draggable document-list columns** — see
|
||||
[Document-list resizing, persistence and drag-drop columns](#document-list-resizing-persistence-and-drag-drop-columns);
|
||||
the search-results list is now configurable with the same column model.
|
||||
- **Dynamic Tags column** — the search-results tags column and its `getTags` call are now gated by
|
||||
`tagsService.areTagsEnabled()` and driven by `app.config.json`.
|
||||
- **Manage permissions from the viewer** — the *Manage permissions* action can now be triggered from inside a file
|
||||
preview.
|
||||
- **`AppExtensionService.updateSidebarActions()`** — a new (additive) public method that publishes
|
||||
`features.sidebar.toolbar` content actions; new `areTagsEnabled` / `areCategoriesEnabled` rule functions are
|
||||
exported from `@alfresco/aca-shared/rules`.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Smart folders | *Edit aspects*, *Manage rules* and *Manage permissions* are now hidden for smart folders, and *Manage permissions* is hidden on multi-selection. |
|
||||
| Records | *Edit Offline* and *Upload New Version* are hidden for declared records. |
|
||||
| Storage | The local-storage prefix is set from the current username on login (via the unified `getUsername()` accessor), fixing an ADW prefix issue. |
|
||||
| Libraries | After deleting a library from the Manage Members view, the user is redirected to the libraries page. |
|
||||
| Search input | Clicking a search input that already contains text now lets you edit the term. |
|
||||
| Viewer | *View details* is active in the expanded view. |
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
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. |
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
Title: Upgrading from ACA v5.0.1 to v5.1.1
|
||||
---
|
||||
|
||||
# Upgrading from ACA v5.0.1 to v5.1.1
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.0.1 project to
|
||||
v5.1.1 (there was no 5.1.0 release).
|
||||
|
||||
This is a small release on the ADF 7.0 alpha line: it moves **ADF 7.0.0-alpha.2 → 7.0.0-alpha.3** and
|
||||
`@alfresco/js-api` 8.0.0-alpha.2 → 8.0.0-alpha.3. Angular (15.2), TypeScript (4.9), rxjs, Nx, zone.js and Node are
|
||||
all **unchanged**. The work is adapting to the ADF alpha.3 **auth + js-api relocation** changes, plus adopting the
|
||||
new **Knowledge Retrieval** feature. The relevant ADF guide is the **7.0.0-alpha.3** section of:
|
||||
|
||||
- [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.3** section)
|
||||
|
||||
Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18
|
||||
(`.nvmrc`) and the Angular 15 platform are unchanged from 5.0.1.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 7.0-alpha.3](#aligning-with-adf-70-alpha3)
|
||||
- [AlfrescoApiService moved to adf-content-services](#alfrescoapiservice-moved-to-adf-content-services)
|
||||
- [Functional route guards](#functional-route-guards)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [aca-playwright-shared is now a published library](#aca-playwright-shared-is-now-a-published-library)
|
||||
- [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": "7.0.0-alpha.3",
|
||||
"@alfresco/adf-content-services": "7.0.0-alpha.3",
|
||||
"@alfresco/adf-extensions": "7.0.0-alpha.3",
|
||||
"@alfresco/js-api": "8.0.0-alpha.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` moves to `7.0.0-alpha.3` too. Angular (`15.2.10`), `@angular/material` (`15.2.9`), TypeScript
|
||||
(`4.9.5`), 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 ADF 7.0-alpha.3
|
||||
|
||||
See the **7.0.0-alpha.3** section of the ADF
|
||||
[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md)
|
||||
("Auth and js-api relocation") for the underlying changes.
|
||||
|
||||
### AlfrescoApiService moved to adf-content-services
|
||||
|
||||
ADF alpha.3 moved `AlfrescoApiService` (and `AlfrescoApiServiceMock`) from `@alfresco/adf-core` to
|
||||
`@alfresco/adf-content-services`. ACA updated all its imports accordingly:
|
||||
|
||||
```ts
|
||||
// Before
|
||||
import { AlfrescoApiService } from '@alfresco/adf-core';
|
||||
|
||||
// After
|
||||
import { AlfrescoApiService } from '@alfresco/adf-content-services';
|
||||
```
|
||||
|
||||
Update this import wherever your fork or extensions use it. (See ADF 7.0.0-alpha.3 → "`AlfrescoApiService` moved
|
||||
from `@alfresco/adf-core` to `@alfresco/adf-content-services`".)
|
||||
|
||||
### Functional route guards
|
||||
|
||||
Following ADF's move to functional route guards (the `AuthGuardBase` class was deleted and the guards became
|
||||
`CanActivateFn` values), ACA converted its own guards to the functional pattern
|
||||
(`view-profile.guard`, `plugin-enabled.guard`, `shared.guard`, and the `extensions-data-loader.guard`). If your
|
||||
fork subclasses ACA guards or references them as injectable classes, migrate to the functional form. (See ADF
|
||||
7.0.0-alpha.3 → "Auth route guards are now functional `CanActivateFn` values".)
|
||||
|
||||
## Breaking changes
|
||||
|
||||
ACA's `@alfresco/aca-shared` and `@alfresco/aca-content` root public APIs are unchanged in this release (no exports
|
||||
removed or renamed). The consumer-facing changes are the ADF import move above and the test-library packaging
|
||||
change below.
|
||||
|
||||
### aca-playwright-shared is now a published library
|
||||
|
||||
`projects/aca-playwright-shared` became a **buildable, publishable Angular library** (it gained `ng-package.json`
|
||||
and `package.json` and is exported for consumers). If you wrote Playwright e2e tests against ACA, you can now
|
||||
import the shared Playwright helpers from the published `@alfresco/aca-playwright-shared` package instead of a
|
||||
relative source path.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Knowledge Retrieval (AI)** — a new feature that returns an AI response for one or more selected files, adopting
|
||||
ADF alpha.3's Knowledge Retrieval / `AgentService` / `SearchAiService`. It adds an `agents-button` and a
|
||||
`search-ai-input-container` component, and can be **toggled in the Docker image** via a runtime env var.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------- | ------------------------------------------------------------------------ |
|
||||
| Document list | The list refreshes after a file version is restored. |
|
||||
| Selection | An error page is shown when an action is invoked with no nodes selected. |
|
||||
| Extensions | Visibility rules now accept arrays (documented). |
|
||||
| Search | The current location is passed as a query parameter. |
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
Title: Upgrading from ACA v5.1 to v5.2
|
||||
---
|
||||
|
||||
# Upgrading from ACA v5.1 to v5.2
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.1.1 project to
|
||||
v5.2.0.
|
||||
|
||||
This release is another platform lift: **Angular 15 → 16**, **TypeScript 4.9 → 5.0**, **rxjs 6 → 7** and
|
||||
**zone.js 0.11 → 0.13**, on **ADF 7.0.0-alpha.3 → 7.0.0-alpha.6** (`@alfresco/js-api` 8.0.0-alpha.3 → alpha.6). The
|
||||
big new feature is **Saved Searches**. The relevant ADF changes are the **7.0.0-alpha.4** (Angular 15 → 16) and
|
||||
**7.0.0-alpha.6** sections of:
|
||||
|
||||
- [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.4** and **7.0.0-alpha.6** sections)
|
||||
|
||||
Nx (17.3.1), `@ngx-translate/core` and Node (`.nvmrc` 18) are unchanged. Because of the Angular 16 / Material 16
|
||||
move, budget time to re-audit Material styles and re-test. Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## 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 16 / TypeScript 5.0 / rxjs 7 / zone.js 0.13** in lockstep. Node 18 (`.nvmrc`) is unchanged.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with Angular 16 / ADF 7.0-alpha](#aligning-with-angular-16--adf-70-alpha)
|
||||
- [Angular 16 migration](#angular-16-migration)
|
||||
- [rxjs 7](#rxjs-7)
|
||||
- [TypeScript 5 class-field initialization](#typescript-5-class-field-initialization)
|
||||
- [Version manager inputs](#version-manager-inputs)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Platform lockstep](#platform-lockstep)
|
||||
- [Context-menu action injection](#context-menu-action-injection)
|
||||
- [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": "16.2.9",
|
||||
"@angular/material": "16.2.9",
|
||||
"typescript": "5.0.4",
|
||||
"rxjs": "7.5.7",
|
||||
"zone.js": "0.13.3",
|
||||
"@ngrx/store": "16.3.0",
|
||||
"@alfresco/adf-core": "7.0.0-alpha.6",
|
||||
"@alfresco/adf-content-services": "7.0.0-alpha.6",
|
||||
"@alfresco/adf-extensions": "7.0.0-alpha.6",
|
||||
"@alfresco/js-api": "8.0.0-alpha.6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli`, the `@angular/*` toolchain, `@angular-eslint/*`, `ng-packagr` and `@ngrx/*` all move to their
|
||||
Angular-16 lines. `nx` (`17.3.1`), `@ngx-translate/core` and Node (`.nvmrc` `18`) are unchanged. Clean
|
||||
`node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with Angular 16 / ADF 7.0-alpha
|
||||
|
||||
See the **7.0.0-alpha.4** / **7.0.0-alpha.6** sections of the ADF
|
||||
[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md)
|
||||
for the underlying changes.
|
||||
|
||||
### Angular 16 migration
|
||||
|
||||
The Angular 16 lift (ACS-6693 / the NG16 migration) rewrote a large amount of ACA to Angular 16 / Material 16 /
|
||||
ngrx 16, with the dominant pattern being **constructor DI → `inject()`** across components, effects and services.
|
||||
A batch of **Material-16 visual fixes** was folded in (checkbox focus colour, create-rule dialog, input fill,
|
||||
sidenav/menu colours). If your fork styles Material internals or overrides ACA component styles, re-audit them.
|
||||
(Some NG16 fixes in that squashed migration were provisional — re-test the areas you customise.)
|
||||
|
||||
### rxjs 7
|
||||
|
||||
rxjs moved 6 → 7. The main source change was tightening empty subjects to **`Subject<void>`**. Note ACA
|
||||
**deliberately kept `toPromise()`** (still present in a handful of services) rather than migrating to
|
||||
`firstValueFrom` / `lastValueFrom`; if you do the migration in your own code, be aware `toPromise` is deprecated in
|
||||
rxjs 7.
|
||||
|
||||
### TypeScript 5 class-field initialization
|
||||
|
||||
TypeScript 5 / Angular 16 enforce stricter class-field semantics (`useDefineForClassFields`): a class-field
|
||||
initializer that references a constructor-injected dependency now runs **before** the constructor assigns it. ACA
|
||||
hit this in `FolderRuleSetsService` (`selectedRuleSet$` referenced an injected service in a field initializer and
|
||||
threw on the Manage Rules page); the fix moved the observable construction into the constructor. **Audit your own
|
||||
field initializers that use injected dependencies** and move them into the constructor (or use `inject()`).
|
||||
|
||||
### Version manager inputs
|
||||
|
||||
Adopting ADF alpha.4's `VersionManagerComponent` inputs, ACA's versions tab now binds `[allowViewVersions]`,
|
||||
`[allowVersionDelete]` and `[showActions]`, driven by new `app.config.json` keys under **`adf-version-manager`**
|
||||
(`allowViewVersions` / `allowVersionDelete` / `showActions`, default `true`) exposed through `AppSettingsService`.
|
||||
|
||||
> The process-services-cloud changes in ADF alpha.4/alpha.6 (`counters$` → `counters`, `RUNNING_STATUS` →
|
||||
> `DEPLOYED_STATUS`, `ContainerModel` getters, the process/task search tokens) do **not** apply to ACA — they are
|
||||
> process-cloud only.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
ACA's published library API is **additive only** this release — no exports were removed, renamed or deprecated
|
||||
(the barrels gain `NavigationHistoryService` in `@alfresco/aca-shared` and `aca-search-utils` in
|
||||
`@alfresco/aca-content`; the store gains a `CustomContextMenu` action). The breaking work is the platform move.
|
||||
|
||||
### Platform lockstep
|
||||
|
||||
You must move your application to **Angular 16, TypeScript 5.0, rxjs 7 and zone.js 0.13** together with ACA. Run
|
||||
the Angular 16 update (`ng update @angular/core@16 @angular/cli@16 @angular/material@16`), address the TypeScript-5
|
||||
class-field caveat above, and re-audit Material 16 styles. A new
|
||||
`@angular-eslint/template/prefer-self-closing-tags` lint rule was enabled (cosmetic template churn).
|
||||
|
||||
### Context-menu action injection
|
||||
|
||||
The context menu was split so custom actions can be injected. A new base directive **`[acaContextActions]`** (with
|
||||
a `customActions` `@Input()`), a `CustomContextMenuComponent`, and a new injection token
|
||||
**`CONTEXT_MENU_CUSTOM_ACTIONS`** were added, alongside a store `CustomContextMenu` action. There are now two
|
||||
population modes: the default `acaContextActions` (loads from `app.extensions.json`) or injecting an array of
|
||||
rule-formatted actions via `customActions` / the token. This is additive, but if you customised the context menu,
|
||||
see `docs/features/context-menu-actions.md` for the new model.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Saved Searches** — save the current search, manage saved searches, and edit / save-as-new. Adds a
|
||||
`save-search` dialog and an `[acaSaveSearch]` directive, a full-page **Manage Searches** list at the new
|
||||
`saved-searches` route (`SavedSearchesSmartListComponent`, guarded by `AuthGuard`), and a sidenav entry
|
||||
registered as the `app.search.navbar` extension component (under a new `app.navbar.secondary` group in
|
||||
`app.extensions.json`). It is backed by ADF's `SavedSearchesService` / `SavedSearch` (ADF 7.0-alpha.4).
|
||||
- **Context-menu custom-action injection** — see [Context-menu action injection](#context-menu-action-injection).
|
||||
- **`NavigationHistoryService`** (`@alfresco/aca-shared`) — tracks router history so views can restore the last
|
||||
selection (used by the Knowledge Retrieval "keep selection on back-navigation" behaviour).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Knowledge Retrieval | Agent avatars are loaded from the backend (previously mocked); the query/question is removed from the input on the results page; selections and the question are kept when navigating back to the previous page. |
|
||||
| Pagination | The items-per-page selector button is now visible. |
|
||||
| Version manager | Whether versions can be viewed/deleted and whether actions show is now configurable via `app.config.json` (`adf-version-manager.*`). |
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
Title: Upgrading from ACA v5.2 to v5.3
|
||||
---
|
||||
|
||||
# Upgrading from ACA v5.2 to v5.3
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.2.0 project to
|
||||
v5.3.0.
|
||||
|
||||
This is a small maintenance release on the ADF 7.0 alpha line: it moves **ADF 7.0.0-alpha.6 → 7.0.0-alpha.7** and
|
||||
`@alfresco/js-api` 8.0.0-alpha.6 → 8.0.0-alpha.7, bumps **rxjs 7.5.7 → 7.8.1** and patches
|
||||
`@angular-devkit/build-angular` (16.2.9 → 16.2.16). Angular (16.2.9), Material (16.2.9), TypeScript (5.0.4),
|
||||
zone.js (0.13.3), Nx (17.3.1) and Node (`.nvmrc` 18) are all **unchanged**. Most of ADF's alpha.7 changes are
|
||||
`process-services-cloud` only and do not affect ACA, so the work this cycle is mostly ACA's own fixes and a few new
|
||||
capabilities. The corresponding ADF guide is the **7.0.0-alpha.7** section of:
|
||||
|
||||
- [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.7** section)
|
||||
|
||||
Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 16 /
|
||||
TypeScript 5 platform and Node 18 (`.nvmrc`) are unchanged from 5.2.0.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 7.0-alpha.7](#aligning-with-adf-70-alpha7)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Required component inputs](#required-component-inputs)
|
||||
- [DeleteNodesAction gained an allowUndo argument](#deletenodesaction-gained-an-allowundo-argument)
|
||||
- [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": "7.0.0-alpha.7",
|
||||
"@alfresco/adf-content-services": "7.0.0-alpha.7",
|
||||
"@alfresco/adf-extensions": "7.0.0-alpha.7",
|
||||
"@alfresco/js-api": "8.0.0-alpha.7",
|
||||
"rxjs": "7.8.1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `7.0.0-alpha.7` too, and
|
||||
`@angular-devkit/build-angular` moves `16.2.9 → 16.2.16` (a Vite security bump). Angular (`16.2.9`),
|
||||
`@angular/material` (`16.2.9`), TypeScript (`5.0.4`), zone.js (`0.13.3`), `nx` (`17.3.1`) and Node (`.nvmrc` `18`)
|
||||
are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 7.0-alpha.7
|
||||
|
||||
See the **7.0.0-alpha.7** section of the ADF
|
||||
[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md)
|
||||
for the full detail. ADF alpha.7 is dominated by the **`process-services-cloud` standalone migration and removals**
|
||||
(Start-Task-Cloud components, several process-cloud pipes/directives and NgModules, identity DI tokens) — **none of
|
||||
which apply to ACA**, which does not depend on `@alfresco/adf-process-services-cloud`. The only cross-cutting
|
||||
alpha.7 items are that ADF's `@alfresco/adf-core` peers were pinned to **exact Angular 16.2.9** (ACA already tracks
|
||||
16.2.9, so no change) and that `@alfresco/adf-testing` was removed (ACA dropped that dependency back in 4.4.1). In
|
||||
practice this ADF bump is drop-in for ACA.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
ACA's published library API is effectively unchanged this release — every `@alfresco/aca-shared` and
|
||||
`@alfresco/aca-content` `public-api.ts` barrel is byte-identical between 5.2.0 and 5.3.0 (no exports added, removed
|
||||
or renamed). The two consumer-facing changes below are signature-level.
|
||||
|
||||
> **Non-change (informational):** a migration of Saved Searches from the config file to the preferences API
|
||||
> (ACS-9166) was merged and then **reverted** before 5.3.0, so Saved Searches storage is unchanged from 5.2.0. No
|
||||
> action is needed — this is only noted in case you diff the intermediate commits.
|
||||
|
||||
### Required component inputs
|
||||
|
||||
Following Angular 16's required-inputs feature, several component `@Input()`s were marked
|
||||
`@Input({ required: true })`. Two are on **exported `@alfresco/aca-shared` components**:
|
||||
|
||||
- `ToolbarComponent` — `items` is now required.
|
||||
- `InfoDrawerComponent` — its primary input is now required.
|
||||
|
||||
(Others were applied to internal components: `rule-list` / `rule-list-item`, `datatable-cell-badges`,
|
||||
`search-results-row`, and the sidenav `button-menu` / `expand-menu`.) If your fork or extension instantiates any of
|
||||
these components in a template **without binding the now-required input, the Angular compiler will error**
|
||||
(`NG8008`). Bind the input, or remove the usage.
|
||||
|
||||
### DeleteNodesAction gained an allowUndo argument
|
||||
|
||||
`DeleteNodesAction` (exported from `@alfresco/aca-shared/store`) and
|
||||
`ContentManagementService.deleteNodes()` gained a second parameter, `allowUndo`, defaulting to `true`:
|
||||
|
||||
```ts
|
||||
// aca-shared/store
|
||||
new DeleteNodesAction(payload /* , allowUndo = true */);
|
||||
|
||||
// content-management.service
|
||||
deleteNodes(items: NodeEntry[], allowUndo = true): void;
|
||||
```
|
||||
|
||||
This is backward-compatible (the new argument is optional and preserves the previous behaviour). Pass
|
||||
`allowUndo: false` to delete without offering the **Undo** snackbar action.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Folder information dialog** (MNT-24575) — a new dialog that displays folder details (retrieved via API, with a
|
||||
retry on failure). It is not offered for items in the trashcan.
|
||||
- **Suppressible delete-undo** (ACS-8604) — see
|
||||
[DeleteNodesAction gained an allowUndo argument](#deletenodesaction-gained-an-allowundo-argument); callers can now
|
||||
delete nodes without the Undo snackbar.
|
||||
- **`takeUntilDestroyed` subscription cleanup** (ACS-8959) — ACA adopted Angular's `takeUntilDestroyed` operator
|
||||
(with `DestroyRef`) across the folder-rules components and several `aca-content` components, replacing manual
|
||||
`ngOnDestroy` / `takeUntil(Subject)` teardown. This is an internal refactor, but if your fork subclasses these
|
||||
components or relied on their destroy `Subject`s, adopt the same pattern.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Search input | The search input is now a reactive form control that disallows certain special characters (showing a validation error) and rewrites a leading `text:` to `TEXT:` on submit rather than erroring. |
|
||||
| Search results | A loading spinner is now shown on the search-results page while filtering for files or folders. |
|
||||
| Libraries | The context menu is no longer empty when multiple libraries are selected; the *Join library* option now shows the correct icon. |
|
||||
| Breadcrumb | The file title in the breadcrumb now updates after the file is renamed. |
|
||||
| Sidenav | The `expandedSidenav` flag is removed from local storage on logout. |
|
||||
| Info drawer | Tag styling is applied to tags shown in the info drawer. |
|
||||
| Saved searches | Long saved-search descriptions are truncated. |
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
Title: Upgrading from ACA v5.3 to v6.0
|
||||
---
|
||||
|
||||
# Upgrading from ACA v5.3 to v6.0
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.3.0 project to
|
||||
v6.0.0.
|
||||
|
||||
**This is a major release.** The headline changes are **Angular 16 → 17**, **Node 18 → 20**, and ADF /
|
||||
`@alfresco/js-api` reaching their **final `7.0.0` / `8.0.0`** releases (from `7.0.0-alpha.7` / `8.0.0-alpha.7`). It
|
||||
also moves **TypeScript 5.0 → 5.3**, **zone.js 0.13 → 0.14**, and **NgRx 16 → 17**. The relevant ADF change is the
|
||||
**7.0.0 (final)** section — the Angular 17 step — of:
|
||||
|
||||
- [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 (final)** section)
|
||||
|
||||
Because of the Angular 17 / Material 17 move and the Node 20 bump, budget time to rebuild your toolchain, re-audit
|
||||
Material styles and re-test. 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. Move your
|
||||
application to **Angular 17 / TypeScript 5.3 / zone.js 0.14 / NgRx 17** in lockstep, and update your build/CI
|
||||
environment to **Node 20** (`.nvmrc` is now `20.18.1`).
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with Angular 17 / ADF 7.0](#aligning-with-angular-17--adf-70)
|
||||
- [Angular 17 migration](#angular-17-migration)
|
||||
- [Node 20](#node-20)
|
||||
- [ADF 7.0 final — what applies to ACA](#adf-70-final--what-applies-to-aca)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Platform lockstep](#platform-lockstep)
|
||||
- [Library public API](#library-public-api)
|
||||
- [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": "7.0.0",
|
||||
"@alfresco/adf-content-services": "7.0.0",
|
||||
"@alfresco/adf-extensions": "7.0.0",
|
||||
"@alfresco/js-api": "8.0.0",
|
||||
"@angular/core": "17.1.3",
|
||||
"@angular/material": "17.1.2",
|
||||
"@ngrx/store": "17.0.1",
|
||||
"typescript": "5.3.3",
|
||||
"zone.js": "0.14.8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The whole `@angular/*` toolchain moves to `17.1.x`, `@ngrx/*` to `17.0.1`, `@angular-eslint/*` to `17.x`,
|
||||
`@typescript-eslint/*` `5 → 6.21.0`, `@nx/*` `17.0.2 → 17.3.2`, `ng-packagr` `16 → 17.1.2`,
|
||||
`@mat-datetimepicker/core` `12 → 13`, `tslib` `→ 2.8.1`, and `@alfresco/adf-cli` /
|
||||
`@alfresco/eslint-plugin-eslint-angular` to `7.0.0`. `rxjs` stays `7.8.1`. **Node moves 18 → 20.18.1** (`.nvmrc`).
|
||||
Unlike ADF (which migrated its test runner to Jest in 7.0.0), **ACA keeps Karma/Jasmine**. Clean `node_modules` and
|
||||
the lockfile, then reinstall.
|
||||
|
||||
## Aligning with Angular 17 / ADF 7.0
|
||||
|
||||
See the **7.0.0 (final)** section of the ADF
|
||||
[6.9 → 7.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade69-70.md)
|
||||
for the underlying platform detail.
|
||||
|
||||
### Angular 17 migration
|
||||
|
||||
ACA was lifted to Angular 17 / Material 17 / NgRx 17 (ACS-6849). Run the Angular 17 update
|
||||
(`ng update @angular/core@17 @angular/cli@17 @angular/material@17`) against your fork. **ACA did not adopt Angular
|
||||
17's new built-in control-flow syntax** (the `@if` / `@for` blocks); templates still use the classic `ngIf` / `ngFor` structural directives, so you do not
|
||||
need to run that migration to stay aligned. Re-audit any Material style overrides against Angular 17.
|
||||
|
||||
### Node 20
|
||||
|
||||
The build now requires **Node 20** (`.nvmrc` `20.18.1`, MNT-24892). Update your local toolchain, Docker base image
|
||||
and CI runners to Node 20; Node 18 is no longer supported.
|
||||
|
||||
### ADF 7.0 final — what applies to ACA
|
||||
|
||||
Most of ADF 7.0.0's breaking removals are in areas ACA does not consume:
|
||||
|
||||
- **`MomentDatePipe` / `MomentDateTimePipe` removed** — ACA does not use them (no change needed).
|
||||
- The `FormModel` / `FullNamePipe` signature changes, the new form-validator injection tokens, the service-task
|
||||
data-shape change and the Screens API are **process/forms-cloud** concerns and do not apply to ACA.
|
||||
|
||||
What ACA does pick up from ADF 7.0.0:
|
||||
|
||||
- **`DocumentListComponent` `displayDragAndDropHint` input** — ACA binds this to hide the drag-and-drop upload hint
|
||||
when files cannot be uploaded to the current location (see [New components and features](#new-components-and-features)).
|
||||
- **`SavedSearchesPreferencesApiService` / `SAVED_SEARCHES_SERVICE_PREFERENCES`** — ADF 7.0.0 made Saved Searches
|
||||
persist through the Preferences API, which ACA now adopts (see below).
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Platform lockstep
|
||||
|
||||
You must move your application to **Angular 17, TypeScript 5.3, zone.js 0.14 and NgRx 17** together with ACA, and
|
||||
run it on **Node 20**. This is the dominant breaking change; there are no ACA source-API removals in this release.
|
||||
|
||||
### Library public API
|
||||
|
||||
The published ACA libraries are **additive only** — no exports were removed or renamed (only the copyright header
|
||||
year changed across the barrels). `@alfresco/aca-content` gains two new exports:
|
||||
|
||||
- **`ContentManagementService`** — the content-management service is now part of the public API (previously
|
||||
internal), so extensions can call it directly.
|
||||
- **`ExternalNodePermissionCommentsTabService`** — a new **abstract** service (`canAddComments(node): boolean`)
|
||||
intended as a DI override point, letting a downstream app decide whether comments can be added for a node (e.g.
|
||||
on retained / record documents).
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Saved Searches persisted via the Preferences API** (ACS-9166) — Saved Searches now persist through the
|
||||
Alfresco Preferences API (adopting ADF 7.0.0's `SavedSearchesPreferencesApiService`) instead of the config file.
|
||||
(This migration was first attempted in the 5.3.0 cycle and reverted; it lands in 6.0.0.)
|
||||
- **Comments extension point** — the new `ExternalNodePermissionCommentsTabService` lets an app control comment
|
||||
availability; ACA uses it so comment creation is available on documents that have been retained / declared as
|
||||
records (ACS-9083).
|
||||
- **Drag-and-drop hint gating** (ACS-8782) — the drag-and-drop upload hint is hidden when files cannot be uploaded
|
||||
to the current location (e.g. frozen files under a hold); this is what surfaced `ContentManagementService` as a
|
||||
public export.
|
||||
- **Accessibility** — the notification and user menus are now keyboard-accessible (ACS-9266), plus a wave of a11y
|
||||
fixes across the sidebar, search page, breadcrumbs and Create Rule dialog (colour-contrast thresholds, supported
|
||||
ARIA attributes, and discernible button text — ACS-9225 / 9228 / 9229 / 9235 / 9236).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Node Details page | The *View Details* button was removed from the node Details page (ACS-9158). |
|
||||
| Extensions | Extension visibility rules are used in **array** form in `app.extensions.json`; single-element arrays no longer log errors (ACS-9346 / ACS-9369). |
|
||||
| Records mgmt | The permission error message shown when opening a records-management library was changed (ACS-9344). |
|
||||
| Saved searches | The Saved Search navbar title is now translated (ACS-9119). |
|
||||
| Login | The license displayed on the login page is updated from SSO (ACS-9213). |
|
||||
| Search input | Search-input focus styles were fixed (ACA-4735). |
|
||||
| Documentation | Product documentation links moved from `docs.alfresco.com` to `support.hyland.com` (ACS-9371); update any hardcoded doc links in a fork. |
|
||||
@@ -0,0 +1,195 @@
|
||||
---
|
||||
Title: Upgrading from ACA v6.0 to v7.0.1
|
||||
---
|
||||
|
||||
# Upgrading from ACA v6.0 to v7.0.1
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v6.0.0 project to
|
||||
v7.0.1 (covering the 7.0.0 and 7.0.1 releases).
|
||||
|
||||
**This is the largest release in the series.** It moves **Angular 17 → 19** (via an internal 18 step), converts
|
||||
ACA into a **standalone-bootstrapped application** (the root `AppModule` is gone), and takes ADF /
|
||||
`@alfresco/js-api` to **8.0.0 / 9.0.0**. Alongside that it upgrades **`@ngx-translate/core` 14 → 16**, **pdf.js
|
||||
3 → 5**, **NgRx 17 → 19**, **TypeScript 5.3 → 5.8**, **zone.js 0.14 → 0.15**, **Nx 17 → 21**, and **Node 20 → 22**.
|
||||
It also adds a markdown/diagram rendering stack (`ngx-markdown`, `mermaid`, `katex`, `prismjs`) for Knowledge
|
||||
Retrieval. The corresponding ADF guide is:
|
||||
|
||||
- [ADF — Upgrading from v7.0 to v8.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md)
|
||||
|
||||
Budget substantial time: you must migrate to Angular 19, adopt the standalone bootstrap, migrate your i18n setup,
|
||||
re-audit your theme against ADF's theming clean-up, and move your PDF viewer worker asset. 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. Move your
|
||||
application to **Angular 19 / TypeScript 5.8 / zone.js 0.15 / NgRx 19** in lockstep, update your build/CI
|
||||
environment to **Node 22** (`.nvmrc` is now `22.14.0`), and plan for the **standalone bootstrap** and **theming**
|
||||
migrations below.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with Angular 19 / ADF 8.0](#aligning-with-angular-19--adf-80)
|
||||
- [Angular 19 migration](#angular-19-migration)
|
||||
- [Standalone application bootstrap](#standalone-application-bootstrap)
|
||||
- [Internationalisation — ngx-translate 16](#internationalisation--ngx-translate-16)
|
||||
- [Theming clean-up](#theming-clean-up)
|
||||
- [PDF viewer — pdf.js 5](#pdf-viewer--pdfjs-5)
|
||||
- [Node 22](#node-22)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Platform lockstep](#platform-lockstep)
|
||||
- [Standalone bootstrap and extension registration](#standalone-bootstrap-and-extension-registration)
|
||||
- [Library public API](#library-public-api)
|
||||
- [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.1",
|
||||
"@alfresco/adf-content-services": "8.0.1",
|
||||
"@alfresco/adf-extensions": "8.0.1",
|
||||
"@alfresco/js-api": "9.0.1",
|
||||
"@angular/core": "19.2.6",
|
||||
"@angular/material": "19.2.9",
|
||||
"@ngrx/store": "19.2.1",
|
||||
"@ngrx/operators": "19.2.1",
|
||||
"@ngx-translate/core": "^16.0.4",
|
||||
"pdfjs-dist": "^5.1.91",
|
||||
"typescript": "5.8.2",
|
||||
"zone.js": "0.15.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The whole `@angular/*` toolchain moves to `19.2.x`, `@ngrx/*` to `19.2.1` (with the new **`@ngrx/operators`**
|
||||
package), `@angular-eslint/*` to `19.3.0`, `@typescript-eslint/*` `6 → 7/8`, `@nx/*` and `nx` `17 → 20/21`,
|
||||
`ng-packagr` `17 → 19`, `@mat-datetimepicker/core` `13 → 15`, `prettier` `2 → 3.5`, and `@alfresco/adf-cli` /
|
||||
`@alfresco/eslint-plugin-eslint-angular` to `8.0.1`. New runtime dependencies **`ngx-markdown` `19.1.1`,
|
||||
`mermaid`, `katex` and `prismjs`** are added for Knowledge Retrieval. `rxjs` moves `7.8.1 → 7.8.2`. **Node moves
|
||||
20 → 22.14.0** (`.nvmrc`). ACA still uses **Karma/Jasmine**. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
> The **7.0.1** patch bumps ADF `8.0.0 → 8.0.1` and `@alfresco/js-api` `9.0.0 → 9.0.1`, fixes an SSO login
|
||||
> regression (see [Standalone application bootstrap](#standalone-application-bootstrap)), and pulls in a
|
||||
> `form-data` security bump. There are no other functional changes between 7.0.0 and 7.0.1.
|
||||
|
||||
## Aligning with Angular 19 / ADF 8.0
|
||||
|
||||
See the ADF [7.0 → 8.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md)
|
||||
for the underlying platform detail — the sections below map ACA's work onto it.
|
||||
|
||||
### Angular 19 migration
|
||||
|
||||
ACA was lifted through **Angular 18** (#4448) and then **Angular 19** (#4520). Run the Angular update schematics
|
||||
in the same order (`ng update @angular/core@18 @angular/cli@18 …` then `@19`), and re-audit Material style overrides
|
||||
against Angular 19's Material.
|
||||
|
||||
### Standalone application bootstrap
|
||||
|
||||
ACA is now a **standalone-bootstrapped application** (AAE-36484 / AAE-36580): the root `AppModule` was removed and
|
||||
`app/src/main.ts` calls `bootstrapApplication(AppComponent, AppConfig)`, where `AppConfig` is an
|
||||
`ApplicationConfig` of providers. If your fork maintains its own root module or `main.ts`, migrate to the
|
||||
standalone bootstrap and register providers (including ACA's, via `provideExtensions()` — see
|
||||
[Standalone bootstrap and extension registration](#standalone-bootstrap-and-extension-registration)).
|
||||
|
||||
> **Provider ordering (SSO):** with the standalone bootstrap, the order of providers in `AppConfig` matters. A
|
||||
> login regression fixed in **7.0.1** (ACS-9934) was caused by `provideTranslations('app', 'assets')` being
|
||||
> registered before the auth module; the fix moves `importProvidersFrom(AuthModule.forRoot({ useHash: true }))`
|
||||
> **ahead of** `provideTranslations(...)`. If SSO login fails after your standalone migration, check that the auth
|
||||
> providers are registered before the translation providers.
|
||||
|
||||
### Internationalisation — ngx-translate 16
|
||||
|
||||
`@ngx-translate/core` moved `14 → 16`, whose provider API changed. Follow ADF's
|
||||
[i18n section](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md#internationalisation-i18n)
|
||||
and register translations through the new provider functions in your standalone `ApplicationConfig` rather than the
|
||||
old `TranslateModule.forRoot()` NgModule import.
|
||||
|
||||
### Theming clean-up
|
||||
|
||||
ADF 8.0 removed its prebuilt themes and colour/variable SCSS partials. In step with this, ACA **broke its
|
||||
dependency on ADF Material selectors** (AAE-34494) and **added the missing palette colour variables** locally
|
||||
(#4535). If your fork `@import`s ADF theme partials or styles ADF components through `.mat-*` selectors, re-audit
|
||||
your SCSS against ADF's [theming clean-up](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md#theming-clean-up).
|
||||
|
||||
### PDF viewer — pdf.js 5
|
||||
|
||||
`pdfjs-dist` moved `3.x → 5.x`. If your fork bundles or overrides the PDF worker asset, update it to the pdf.js 5
|
||||
worker per ADF's [PDF viewer section](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade70-80.md#pdf-viewer-pdfjs-5).
|
||||
|
||||
### Node 22
|
||||
|
||||
The build now requires **Node 22** (`.nvmrc` `22.14.0`). Update your local toolchain, Docker base image and CI
|
||||
runners; Node 20 is no longer supported.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Platform lockstep
|
||||
|
||||
You must move your application to **Angular 19, TypeScript 5.8, zone.js 0.15 and NgRx 19** (adding the new
|
||||
`@ngrx/operators` package) together with ACA, and run it on **Node 22**. This — together with the standalone
|
||||
bootstrap below — is the dominant breaking change.
|
||||
|
||||
### Standalone bootstrap and extension registration
|
||||
|
||||
Because the root `AppModule` was removed, ACA's extensions are no longer registered by importing an NgModule.
|
||||
`@alfresco/aca-content` now exports a **`provideExtensions()`** function (built on Angular 19's
|
||||
`provideAppInitializer` / `inject`) that returns the providers to add to your standalone `ApplicationConfig`:
|
||||
|
||||
```ts
|
||||
import { provideExtensions } from '@alfresco/aca-content';
|
||||
|
||||
export const AppConfig: ApplicationConfig = {
|
||||
providers: [
|
||||
// …
|
||||
provideExtensions()
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
If your fork registered ACA via an NgModule import, switch to `provideExtensions()` in your bootstrap providers.
|
||||
|
||||
### Library public API
|
||||
|
||||
The published ACA libraries **removed** the following exports:
|
||||
|
||||
- **`@alfresco/aca-shared`** — the deprecated **`shared.module`** and **`shared-toolbar.module`** NgModules were
|
||||
removed. Import the standalone components/directives you need directly instead of these modules.
|
||||
- **`@alfresco/aca-shared/store`** — the **`snackbar.actions`** and **`snackbar.effects`** were removed. Snackbar
|
||||
handling now goes through ADF's `NotificationService` (this completes the migration started in earlier releases);
|
||||
if you dispatched ACA snackbar actions, call the ADF service instead.
|
||||
|
||||
Additive:
|
||||
|
||||
- **`@alfresco/aca-content`** — new **`provideExtensions()`** export (see above).
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Markdown rendering in Knowledge Retrieval** — AI responses now render **Markdown** (ACS-9427) via
|
||||
`ngx-markdown`, including code highlighting (`prismjs`), diagrams (`mermaid`) and math (`katex`). Links embedded in
|
||||
a response open in a **separate browser tab** (ACS-9535), and the repeated-question behaviour was fixed
|
||||
(ACS-9546).
|
||||
- **Folder Information enhancements** — the folder-information dialog now shows the **number of files** (ACS-9249)
|
||||
and no longer displays an error while the API response is `IN_PROGRESS` (ACS-9466).
|
||||
- **Favorite action notifications** (ACS-9398) — adding/removing favorites now shows snackbar notifications.
|
||||
- **Folder-rule script name** (MNT-25175) — the folder-rule display now shows the script name.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Viewer | The print button is now hidden / disabled for media files (ACS-9388). |
|
||||
| Login | The login screen uses a white background and forces a light colour scheme (ACS-9670). |
|
||||
| Permissions | The user is redirected away from the permissions page after the node is deleted (ACS-9554). |
|
||||
| About page | Tasks and processes are displayed correctly when the About page is refreshed (ACS-9510). |
|
||||
| Search | Property fields are now included in search header calls (MNT-24848). |
|
||||
| Libraries | Library-permission warnings now use the notification service (with yellow warning styling) instead of the store (ACS-8746). |
|
||||
| Folder rules | An invalid rule definition shows a correct error message (ACS-5503); the edit-rule dialog uses the correct title/button text (ACS-9386). |
|
||||
| Legal hold | Legal-hold capabilities are verified correctly (MNT-24923). |
|
||||
| Accessibility | Focus is restored after a dialog is closed (ACS-9702). |
|
||||
| Metadata sidebar | Several metadata-sidebar issues were fixed (ACS-9789). |
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
Title: Upgrading from ACA v7.0.1 to v7.1.0
|
||||
---
|
||||
|
||||
# Upgrading from ACA v7.0.1 to v7.1.0
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.0.1 project to
|
||||
v7.1.0.
|
||||
|
||||
This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.0.1 → 8.1.1** and `@alfresco/js-api`
|
||||
9.0.1 → 9.1.1. Angular (19.2), Material, TypeScript (5.8), zone.js, NgRx (19.2) and Node (`.nvmrc` 22.14.0) are all
|
||||
**unchanged** version-wise. The main consumer-facing work is a **provider-API migration** for extension
|
||||
registration (finishing the standalone move started in 7.0.0) and an **NgRx API modernisation**. The corresponding
|
||||
ADF guide is:
|
||||
|
||||
- [ADF — Upgrading from v8.0 to v8.1.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade80-811.md)
|
||||
|
||||
Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 /
|
||||
TypeScript 5.8 platform and Node 22 (`.nvmrc`) are unchanged from 7.0.1.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 8.1](#aligning-with-adf-81)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Extension registration moved to the provider API](#extension-registration-moved-to-the-provider-api)
|
||||
- [NgRx API modernisation](#ngrx-api-modernisation)
|
||||
- [Build dependencies](#build-dependencies)
|
||||
- [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.1.1",
|
||||
"@alfresco/adf-content-services": "8.1.1",
|
||||
"@alfresco/adf-extensions": "8.1.1",
|
||||
"@alfresco/js-api": "9.1.1",
|
||||
"date-fns": "^4.1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `8.1.1` too. `date-fns` moves
|
||||
`2.30.0 → 4.1.0` (a major bump — in ACA it is only used by the `@alfresco/aca-playwright-shared` test utilities),
|
||||
`mermaid` `11.8 → 11.10`, and `nx` / `@nx/*` `21.2 → 21.3`. Angular (`19.2.6`), `@angular/material` (`19.2.9`),
|
||||
TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node (`.nvmrc` `22.14.0`) are unchanged. Clean
|
||||
`node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 8.1
|
||||
|
||||
See the ADF [8.0 → 8.1.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade80-811.md)
|
||||
for the underlying library changes. ACA simply consumes ADF `8.1.1` / js-api `9.1.1`; there is no ADF-driven
|
||||
source migration required in ACA beyond adopting the versions.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Extension registration moved to the provider API
|
||||
|
||||
ACA completed its move to Angular's provider API for extension registration (AAE-37293). The short-lived
|
||||
`provideExtensions()` function that `@alfresco/aca-content` exported in 7.0.0 has been **removed**, along with the
|
||||
`CoreExtensionsModule` (`core.extensions.module`) export. Extension registration now goes through:
|
||||
|
||||
- **`provideContentAppExtensions()`** — a new function exported from **`@alfresco/aca-shared`**, and
|
||||
- your own application-level extensions provider (in ACA, `provideApplicationExtensions()` from
|
||||
`app/src/app/extensions.module.ts`).
|
||||
|
||||
```ts
|
||||
// Before (7.0.x)
|
||||
import { provideExtensions } from '@alfresco/aca-content';
|
||||
// providers: [ …, provideExtensions() ]
|
||||
|
||||
// After (7.1.0)
|
||||
import { provideContentAppExtensions } from '@alfresco/aca-shared';
|
||||
// providers: [ …, provideContentAppExtensions(), provideApplicationExtensions() ]
|
||||
```
|
||||
|
||||
Internally the content library now registers its components/guards through ADF's own
|
||||
`provideExtensions` / `provideAppExtensions` (from `@alfresco/adf-extensions`). If your fork registered ACA
|
||||
extensions via `provideExtensions()` from `@alfresco/aca-content` or imported `CoreExtensionsModule`, switch to
|
||||
`provideContentAppExtensions()`.
|
||||
|
||||
### NgRx API modernisation
|
||||
|
||||
ACA's store was upgraded to the modern NgRx API (ACS-9911), including the effect and testing-module setup
|
||||
(`app-testing.module` / `lib-testing-module` and the effects specs). If your fork extends ACA's effects or reuses
|
||||
its testing modules, align them with the updated NgRx provider/testing API.
|
||||
|
||||
### Build dependencies
|
||||
|
||||
- **`@angular/cli` and `@schematics/angular` were removed** from `devDependencies` (AAE-37689) — the workspace
|
||||
builds through Nx executors, not the Angular CLI. If your fork invokes `ng` directly, add the CLI back to your
|
||||
own `devDependencies` or switch to the Nx equivalents.
|
||||
- **`date-fns` moved `2 → 4`** (major). ACA only uses it in the Playwright test utilities, but if your fork uses
|
||||
`date-fns` directly, review the v3/v4 breaking changes.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **`provideContentAppExtensions()`** (`@alfresco/aca-shared`) — the new provider-API entry point for registering
|
||||
ACA's content extensions (see [Extension registration moved to the provider API](#extension-registration-moved-to-the-provider-api)).
|
||||
- **`noWhitespaceValidator`** (`@alfresco/aca-shared`) — a new reusable Angular form `ValidatorFn` that rejects
|
||||
whitespace-only input.
|
||||
- **Current ACS version selector** (ACS-9907) — a new store selector in `@alfresco/aca-shared/store` exposes the
|
||||
current ACS repository version.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Search | The search popup no longer flickers on Enter, and the infinite loading animation on the search results was fixed (ACS-9374 / ACS-9590). |
|
||||
| Search | Search requests are no longer altered when the query uses quote marks (MNT-25070). |
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
Title: Upgrading from ACA v7.1.0 to v7.2.0
|
||||
---
|
||||
|
||||
# Upgrading from ACA v7.1.0 to v7.2.0
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.1.0 project to
|
||||
v7.2.0.
|
||||
|
||||
This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.1.1 → 8.2.1** and `@alfresco/js-api`
|
||||
9.1.1 → 9.2.1. Angular (19.2), Material, TypeScript (5.8), zone.js, NgRx (19.2) and Node (`.nvmrc` 22.14.0) are
|
||||
**unchanged**. Despite being a minor bump, it carries a few consumer-facing items: an **OAuth config change**,
|
||||
**ADF removed from the libraries' peer dependencies**, the continuation of the **ADF → ACA theming decoupling**,
|
||||
new **All Libraries** and **custom user-profile-section** capabilities, and a large **accessibility** pass. The
|
||||
corresponding ADF guide is:
|
||||
|
||||
- [ADF — Upgrading from v8.1.1 to v8.2.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade811-821.md)
|
||||
|
||||
Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 /
|
||||
TypeScript 5.8 platform and Node 22 (`.nvmrc`) are unchanged from 7.1.0.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 8.2](#aligning-with-adf-82)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [OAuth configuration — secret field removed](#oauth-configuration--secret-field-removed)
|
||||
- [ADF removed from library peer dependencies](#adf-removed-from-library-peer-dependencies)
|
||||
- [Theme variables moved from ADF to ACA](#theme-variables-moved-from-adf-to-aca)
|
||||
- [Deprecated API and module cleanup](#deprecated-api-and-module-cleanup)
|
||||
- [Library public API](#library-public-api)
|
||||
- [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-extensions": "8.2.1",
|
||||
"@alfresco/js-api": "9.2.1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `8.2.1` too. Dev tooling advances
|
||||
(`nx` / `@nx/*` `21.3 → 21.5`, `@playwright/test` `1.53 → 1.56`, `jasmine-core` `4.6 → 5.12`, `dotenv` `16 → 17`),
|
||||
a `webpack-bundle-analyzer` devDependency and several `ci:*` npm scripts were added. Angular (`19.2.6`),
|
||||
`@angular/material` (`19.2.9`), TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node
|
||||
(`.nvmrc` `22.14.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 8.2
|
||||
|
||||
See the ADF [8.1.1 → 8.2.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade811-821.md)
|
||||
for the underlying library changes. Beyond adopting ADF `8.2.1` / js-api `9.2.1`, the ADF-driven work in ACA is the
|
||||
**theming decoupling** below — ACA now owns the theme variables it previously inherited from ADF.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### OAuth configuration — secret field removed
|
||||
|
||||
The empty **`secret`** field was removed from the OAuth2 block of `app.config.json` across ADF / ACA / ADW
|
||||
(ACS-10592). Remove `oauth2.secret` from any custom `app.config.json`.
|
||||
|
||||
### ADF removed from library peer dependencies
|
||||
|
||||
`@alfresco/adf-*` was **removed from the `peerDependencies`** of ACA's published libraries (`@alfresco/aca-shared`,
|
||||
`@alfresco/aca-content`) — AAE-37857. Consuming projects are now responsible for declaring and aligning their own
|
||||
ADF versions; ACA no longer pins them for you.
|
||||
|
||||
### Theme variables moved from ADF to ACA
|
||||
|
||||
Continuing the theming decoupling, ACA now defines locally the theme variables it previously inherited from ADF
|
||||
(ACS-10448 added `projects/aca-content/src/lib/ui/overrides/adf-variables.scss`). If your fork relied on ADF theme
|
||||
variables being provided transitively through ACA, re-audit your SCSS against the new ACA-owned variables.
|
||||
|
||||
### Deprecated API and module cleanup
|
||||
|
||||
ACA removed deprecated methods from its auth-related components (ACS-9768) and replaced other deprecated APIs and
|
||||
modules (ACS-9859). If your fork subclasses those components or calls the removed methods, migrate to the current
|
||||
equivalents.
|
||||
|
||||
### Library public API
|
||||
|
||||
The published API is otherwise **additive** — `@alfresco/aca-content` gains an **`isFeatureSupportedInCurrentAcs`**
|
||||
pipe, and `@alfresco/aca-shared` gains a **`UserProfileSection`** type (with
|
||||
`AppExtensionService.getUserProfileSections()`) and an **`isSSOEnabled`** rule (`@alfresco/aca-shared/rules`). No
|
||||
exports were removed or renamed.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **All Libraries page** (ACS-10165) — the libraries screens were refactored onto a shared `libraries-base`
|
||||
component with a new reusable `library-list` component, and a new *all libraries* route was added.
|
||||
- **Custom user-profile sections** (ACS-9980) — you can now contribute custom sections to the user-profile page
|
||||
via a new `userProfileSections` extension in `app.extensions.json`, surfaced through the new `UserProfileSection`
|
||||
type and `AppExtensionService.getUserProfileSections()`.
|
||||
- **Feature gating by ACS version** — a new `isFeatureSupportedInCurrentAcs` pipe (with folder-information and
|
||||
bulk-update evaluators, ACS-10036 / ACS-10038) resolves whether a feature is supported by the connected ACS
|
||||
repository version.
|
||||
- **Saved-searches backward compatibility** — ACA now also supports the legacy `config.json`-based saved-searches
|
||||
approach alongside the Preferences API (ACS-10421), and ADW/ACA gracefully handle repositories below ACS 25.x
|
||||
that do not support the preferences `PUT` method (ACS-10035).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Search | The search results page now renders the Description / Title fields as **plain text** instead of interpreting embedded HTML (ACS-10116). |
|
||||
| Search | The search input no longer clears when using a special search such as `text:value` (ACS-10076); filters clear correctly when the input is empty (MNT-25411). |
|
||||
| Search | Filtering now behaves correctly in files and sites (ACS-10083), and switching between saved searches works correctly (MNT-25409). |
|
||||
| Viewer | The version preview can now be changed from within the preview window (MNT-25285). |
|
||||
| Libraries | Permission-checking logic in library navigation was fixed (ACS-10409). |
|
||||
| Navigation | The *Go to personal files* button on the profile page now navigates correctly (ACS-10214); doubled menu-collapsing was removed (MNT-25423). |
|
||||
| Accessibility | A large screen-reader / keyboard pass landed — context-menu keyboard navigation, rule-set header labels, profile-page field labels and error messages, and search clear / save-search dialog icons among others (ACS-10198 / 10238 / 10253 / 10285 / 10286 / 10290 / 10295 / 10297 / 10303). |
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
Title: Upgrading from ACA v7.2.0 to v7.3.0
|
||||
---
|
||||
|
||||
# Upgrading from ACA v7.2.0 to v7.3.0
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.2.0 project to
|
||||
v7.3.0.
|
||||
|
||||
This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.2.1 → 8.3.1** and `@alfresco/js-api`
|
||||
9.2.1 → 9.3.1, and bumps **Node 22 → 24** (`.nvmrc` `24.13.0`). Angular stays on the 19.2 line (a patch bump from
|
||||
`19.2.6` to `19.2.19`), and TypeScript, zone.js and NgRx are unchanged. The bulk of the release is a **large
|
||||
accessibility pass**, plus the `adf-toolbar → mat-toolbar` migration, a generalised node **Information dialog**, and
|
||||
search-query hardening. The corresponding ADF guide is:
|
||||
|
||||
- [ADF — Upgrading from v8.2.1 to v8.3.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade821-831.md)
|
||||
|
||||
Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Update your
|
||||
build/CI environment to **Node 24** (`.nvmrc` is now `24.13.0`); the Angular 19 / TypeScript 5.8 platform is
|
||||
otherwise unchanged from 7.2.0.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 8.3](#aligning-with-adf-83)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Node 24](#node-24)
|
||||
- [adf-toolbar replaced with mat-toolbar](#adf-toolbar-replaced-with-mat-toolbar)
|
||||
- [Build — native Node env loader](#build--native-node-env-loader)
|
||||
- [Library public API](#library-public-api)
|
||||
- [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.3.1",
|
||||
"@alfresco/adf-content-services": "8.3.1",
|
||||
"@alfresco/adf-extensions": "8.3.1",
|
||||
"@alfresco/js-api": "9.3.1",
|
||||
"@angular/core": "19.2.19"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The whole `@angular/*` toolchain moves to the `19.2.19` patch, `@alfresco/adf-cli` /
|
||||
`@alfresco/eslint-plugin-eslint-angular` to `8.3.1`, and dev tooling advances (`@nx/*` `21 → 22`, `jasmine-core`
|
||||
`5 → 6`, `@types/node` `18 → 25`, `eslint-plugin-playwright` `1 → 2`, `mermaid` `11.10 → 11.12`). **Node moves
|
||||
22 → 24.13.0** (`.nvmrc`). `@ngx-translate/core` stays `^16.0.4` (see the note below), and TypeScript (`5.8.2`),
|
||||
`@ngrx/*` (`19.2.1`) and zone.js (`0.15.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
> **Non-change (informational):** an `@ngx-translate/core` upgrade was attempted and **reverted** before 7.3.0
|
||||
> (ACS-11213), so ngx-translate stays at `^16.0.4`. No action is needed — this is only noted in case you diff the
|
||||
> intermediate commits.
|
||||
|
||||
## Aligning with ADF 8.3
|
||||
|
||||
See the ADF [8.2.1 → 8.3.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade821-831.md)
|
||||
for the underlying library changes. ACA consumes ADF `8.3.1` / js-api `9.3.1`; the only notable source adaptation
|
||||
is a refactor of `getChild` usage (ACS-11051) to match the js-api. If your fork calls the same js-api node methods,
|
||||
review them against js-api 9.3.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Node 24
|
||||
|
||||
The build now requires **Node 24** (`.nvmrc` `24.13.0`). Update your local toolchain, Docker base image and CI
|
||||
runners; Node 22 is no longer the target.
|
||||
|
||||
### adf-toolbar replaced with mat-toolbar
|
||||
|
||||
ACA replaced ADF's `<adf-toolbar>` with Angular Material's `<mat-toolbar>` (ACS-10934, e.g. in the Manage Rules
|
||||
screens). If your fork styles the `.adf-toolbar` / `.adf-toolbar--inline` DOM or depends on the ADF toolbar
|
||||
component's markup, re-audit those styles against the Material toolbar.
|
||||
|
||||
### Build — native Node env loader
|
||||
|
||||
The build switched to Node 24's **native `.env` loader**, and `dotenv-expand` was removed as a dependency
|
||||
(#4970). If your fork's scripts relied on `dotenv-expand`, move to the native `--env-file` mechanism.
|
||||
|
||||
### Library public API
|
||||
|
||||
The published API is **additive** — `@alfresco/aca-shared` gains a **`noLeadingTrailingOperatorsValidator`** form
|
||||
validator (used to reject search queries with leading/trailing operators). No exports were removed or renamed.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Node Information dialog** (MNT-25478) — the earlier folder-information dialog was generalised into a node
|
||||
**Information dialog**, adding a new `location-link` component and a dialog for additional location references
|
||||
(for nodes that appear in more than one location).
|
||||
- **Search-query validation** — a new `noLeadingTrailingOperatorsValidator` (ACS-10514) rejects queries with
|
||||
leading/trailing operators, and top-level filter management was added to the search filters (ACS-10083).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Accessibility | A large screen-reader / keyboard / contrast pass landed — sidenav and snackbar now announce state, Esc no longer loses keyboard focus, headings and dropdown labels were corrected, folder-rules and bulk-actions controls were made SR-friendly, favourite add/remove is announced, and colour-contrast was improved in several places (ACS-10200 / 10201 / 10204 / 10217 / 10219 / 10226 / 10233 / 10283 / 10287 / 10293 / 10294 / 10307 / 10323 / 10885 / 10886 among others). |
|
||||
| Search | Leading and trailing operators in a query are now handled correctly (ACS-10514); the *Save Changes* button no longer becomes disabled after modifying the search or filter (ACS-10730); the loader is no longer shown for a nullish query (MNT-25408). |
|
||||
| Sorting | Sorting configured via the sorting key is now saved correctly in local storage (MNT-25276). |
|
||||
| Knowledge Retrieval | The answer page now displays the response instead of a general error, with a workaround for the AI answer references id mapping (ACS-11033). |
|
||||
| Security | Fixed an Angular i18n CSS vulnerability (PRODSEC-11289). |
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
Title: Upgrading from ACA v7.3.0 to v7.4.1
|
||||
---
|
||||
|
||||
# Upgrading from ACA v7.3.0 to v7.4.1
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.3.0 project to
|
||||
v7.4.1 (there was no 7.4.0 release).
|
||||
|
||||
This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.3.1 → 8.4.1** and `@alfresco/js-api`
|
||||
9.3.1 → 9.4.1. Angular stays on the 19.2 line (patch `19.2.19` to `19.2.20`), and Node (`.nvmrc` 24.13.0),
|
||||
TypeScript, zone.js and NgRx are unchanged. The notable items are the **`@ngx-translate/core` 16 → 17** major bump
|
||||
(which was attempted and reverted in 7.3.0, and now lands), a **front-end rebrand**, a new **repository view**, and
|
||||
a **search UX rework** that removed two recently-added form validators. The corresponding ADF guide is:
|
||||
|
||||
- [ADF — Upgrading from v8.3.1 to v8.4.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade831-841.md)
|
||||
|
||||
Read the [breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 /
|
||||
TypeScript 5.8 platform and Node 24 (`.nvmrc`) are unchanged from 7.3.0.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 8.4](#aligning-with-adf-84)
|
||||
- [ngx-translate 17](#ngx-translate-17)
|
||||
- [js-api LazyApi decorator](#js-api-lazyapi-decorator)
|
||||
- [Library peer dependencies](#library-peer-dependencies)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Removed search validators](#removed-search-validators)
|
||||
- [prefer-inject lint rule](#prefer-inject-lint-rule)
|
||||
- [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.4.1",
|
||||
"@alfresco/adf-content-services": "8.4.1",
|
||||
"@alfresco/adf-extensions": "8.4.1",
|
||||
"@alfresco/js-api": "9.4.1",
|
||||
"@ngx-translate/core": "^17.0.0",
|
||||
"@angular/core": "19.2.20"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The whole `@angular/*` toolchain moves to the `19.2.20` patch, `@alfresco/adf-cli` /
|
||||
`@alfresco/eslint-plugin-eslint-angular` to `8.4.1`, `@angular-eslint/*` `19.3 → 19.8.1`, `@nx/*` / `nx`
|
||||
`21/22 → 22.5.4`, and `prettier` `3.5 → 3.8`. `pdfjs-dist` is now pinned exactly (`5.1.91`). **`@ngx-translate/core`
|
||||
moves `16 → 17`** (a major — see below). TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node
|
||||
(`.nvmrc` `24.13.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 8.4
|
||||
|
||||
See the ADF [8.3.1 → 8.4.1 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade831-841.md)
|
||||
for the underlying library changes.
|
||||
|
||||
### ngx-translate 17
|
||||
|
||||
`@ngx-translate/core` moved `16 → 17`. This is the upgrade that was reverted in 7.3.0 and now lands together with
|
||||
ADF 8.4. If your fork registers translation providers or a custom `TranslateLoader`, align them with the
|
||||
ngx-translate 17 API. A related fix ensures the app no longer reverts components to English after switching the
|
||||
language and reloading (ACS-10732).
|
||||
|
||||
### js-api LazyApi decorator
|
||||
|
||||
ACA adopted js-api's new **`LazyApi`** decorator (ACS-11205) and added the `declare` keyword to affected class
|
||||
fields (with a matching `tsconfig` adjustment) to prevent field shadowing under `useDefineForClassFields`. If your
|
||||
fork extends the same js-api-backed services, apply the same pattern.
|
||||
|
||||
### Library peer dependencies
|
||||
|
||||
The published libraries' `peerDependencies` for Angular and NgRx were updated to **v19.2** (#5151). Align your
|
||||
consuming project's Angular / NgRx versions accordingly.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Removed search validators
|
||||
|
||||
As part of the search UX rework (ACS-10475), the two form validators added in the previous releases were
|
||||
**removed** from `@alfresco/aca-shared` (their files were deleted):
|
||||
|
||||
- `noWhitespaceValidator`
|
||||
- `noLeadingTrailingOperatorsValidator`
|
||||
|
||||
If your fork imported either validator from `@alfresco/aca-shared`, inline the check or provide your own
|
||||
`ValidatorFn`; the search input now handles this internally.
|
||||
|
||||
### prefer-inject lint rule
|
||||
|
||||
The `@angular-eslint` **`prefer-inject`** rule was enabled by default (ACS-11417), in line with the Angular 20
|
||||
direction. This is a lint-level change that may produce warnings/errors in a fork that still uses constructor
|
||||
injection; migrate to `inject()` or adjust your lint config.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Repository view** (MNT-25615) — a new `repository-view` component and route that surface the repository
|
||||
(Company Home) root as a browsable location.
|
||||
- **Search UX improvements** (ACS-10475) — a set of front-end search UX refinements (including the internalised
|
||||
input validation that replaced the removed validators above).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Branding | The application was rebranded — the Alfresco logo and favicon were updated (ACS-11271). |
|
||||
| Localisation | Switching the language and reloading no longer reverts components back to English (ACS-10732). |
|
||||
| Records | The *Edit Offline* option is hidden when a node is checked out (MNT-25584). |
|
||||
| Node info | The Information button display was fixed (MNT-25478 follow-up). |
|
||||
| Accessibility | The search page is now readable at 320px width (ACS-10258), and the Saved Search dialog manages focus correctly on open and return to trigger on close (ACS-10273). |
|
||||
| Libraries | Library-properties handling was cleaned up (ACS-10621). |
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
Title: Upgrading from ACA v7.4.1 to v7.5.0
|
||||
---
|
||||
|
||||
# Upgrading from ACA v7.4.1 to v7.5.0
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.4.1 project to
|
||||
v7.5.0.
|
||||
|
||||
This is a minor release on the Angular 19 / ADF 8 line: it moves **ADF 8.4.1 → 8.5.0** and `@alfresco/js-api`
|
||||
9.4.1 → 9.5.0. Angular (19.2), Node (`.nvmrc` 24.13.0), TypeScript, zone.js and NgRx are all **unchanged**. The
|
||||
headline is the **Material Design 3 (MD3) migration** — the biggest source of visual change in this release — plus
|
||||
a new **Link document** capability and multivalued-property support in folder rules. The corresponding ADF guide
|
||||
is:
|
||||
|
||||
- [ADF — Upgrading from v8.4.1 to v8.5.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade841-850.md)
|
||||
|
||||
Because of the MD3 migration, budget time to re-audit any custom theme or Material style overrides. Read the
|
||||
[breaking changes](#breaking-changes).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The Angular 19 /
|
||||
TypeScript 5.8 platform and Node 24 (`.nvmrc`) are unchanged from 7.4.1. Budget time to re-theme (MD3) and re-test.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with ADF 8.5](#aligning-with-adf-85)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Material Design 3 (MD3) migration](#material-design-3-md3-migration)
|
||||
- [minimatch-browser dependency removed](#minimatch-browser-dependency-removed)
|
||||
- [Library public API](#library-public-api)
|
||||
- [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.5.0",
|
||||
"@alfresco/adf-content-services": "8.5.0",
|
||||
"@alfresco/adf-extensions": "8.5.0",
|
||||
"@alfresco/js-api": "9.5.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`@alfresco/adf-cli` and `@alfresco/eslint-plugin-eslint-angular` move to `8.5.0` too, and `mermaid` moves
|
||||
`11.12 → 11.15`. The **`minimatch-browser`** runtime dependency was removed. Angular (`19.2.20`),
|
||||
`@angular/material` (`19.2`), TypeScript (`5.8.2`), `@ngrx/*` (`19.2.1`), zone.js (`0.15.0`) and Node
|
||||
(`.nvmrc` `24.13.0`) are unchanged. Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with ADF 8.5
|
||||
|
||||
See the ADF [8.4.1 → 8.5.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade841-850.md)
|
||||
for the underlying library changes. Beyond adopting ADF `8.5.0` / js-api `9.5.0`, the ADF-aligned work in ACA is
|
||||
the Material Design 3 theming migration below.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Material Design 3 (MD3) migration
|
||||
|
||||
ACA (and ADW / ACC) migrated their theming to **Angular Material 3 (MD3)** — ACS-10449. This reworked the theme
|
||||
across roughly 70 files: `theme.scss`, `custom-theme.scss`, `variables.scss`, the ADF override partials
|
||||
(`adf-style-fixes.theme.scss`, `adf-variables.scss`, `adf-pagination.theme.scss`, …), new `mixins.scss` /
|
||||
`mat-selectors.scss`, and many component SCSS files. MD3 changes Material's design tokens, component styling and
|
||||
CSS custom properties.
|
||||
|
||||
**If your fork defines a custom theme or overrides Material component styles, you must re-audit them against MD3.**
|
||||
This is the largest source of visual breakage in this upgrade.
|
||||
|
||||
### minimatch-browser dependency removed
|
||||
|
||||
The `minimatch-browser` runtime dependency was removed from `package.json`. If your fork imported it transitively
|
||||
through ACA, add it to your own dependencies.
|
||||
|
||||
### Library public API
|
||||
|
||||
The published API is **additive** — `@alfresco/aca-content` now exports the **`NodeActionsService`** (ACS-9765),
|
||||
which also gained *copy/move/link* support (see [New components and features](#new-components-and-features)). No
|
||||
exports were removed or renamed.
|
||||
|
||||
> **Non-change (informational):** a change to how sharable links handle redirects to the login page (ACS-11861)
|
||||
> was merged and then **reverted** before 7.5.0, so that behaviour is unchanged. No action is needed — this is only
|
||||
> noted in case you diff the intermediate commits.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **Link document** (MNT-25522) — you can now create a **link** to a document in another location. This adds a new
|
||||
node store action and extends the now-public `NodeActionsService`; linked nodes display `N/A` for size and number
|
||||
of files in the Information dialog.
|
||||
- **`NodeActionsService`** (`@alfresco/aca-content`) — the copy / move / link service is now part of the public API
|
||||
(`copyNodes()`, `moveNodes()`, and the new link action), so extensions can drive those actions directly.
|
||||
- **Folder rules — multivalued properties** (MNT-25149 / MNT-25558) — folder-rule property conditions and actions
|
||||
now support multivalued properties.
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Accessibility | Focus is handled correctly after collapsing the sidenav menu (ACS-11350), and the info-drawer tabs show a proper focus indicator during keyboard navigation (ACS-11980). |
|
||||
| Styling | General style updates accompanied the MD3 migration (ACS-11158). |
|
||||
| Info dialog | Links display `N/A` for size and number of files (MNT-25522). |
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
Title: Upgrading from ACA v7.5.0 to v8.0.0
|
||||
---
|
||||
|
||||
# Upgrading from ACA v7.5.0 to v8.0.0
|
||||
|
||||
This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v7.5.0 project to
|
||||
v8.0.0.
|
||||
|
||||
**This is a major release.** It moves ACA from **Angular 19 to 20**, takes ADF / `@alfresco/js-api` to their new
|
||||
majors **9.0.0 / 10.0.0**, and upgrades **NgRx 19 → 20** and **TypeScript 5.8 → 5.9**. The most significant
|
||||
functional change is the **removal of the embedded Knowledge Retrieval (AI) feature**, which is replaced by a link
|
||||
to an **external Knowledge Discovery application**. The corresponding ADF guide is:
|
||||
|
||||
- [ADF — Upgrading from v8.5.0 to v9.0.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade850-900.md)
|
||||
|
||||
Budget time to migrate to Angular 20 and re-test. 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. Move your
|
||||
application to **Angular 20 / TypeScript 5.9 / NgRx 20** in lockstep. Node is a patch bump
|
||||
(`.nvmrc` `24.13.0` to `24.13.1`).
|
||||
|
||||
## Contents
|
||||
|
||||
- [Library updates](#library-updates)
|
||||
- [Aligning with Angular 20 / ADF 9.0](#aligning-with-angular-20--adf-90)
|
||||
- [Angular 20 migration](#angular-20-migration)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Platform lockstep](#platform-lockstep)
|
||||
- [Embedded Knowledge Retrieval removed](#embedded-knowledge-retrieval-removed)
|
||||
- [Library public API](#library-public-api)
|
||||
- [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": "9.0.0",
|
||||
"@alfresco/adf-content-services": "9.0.0",
|
||||
"@alfresco/adf-extensions": "9.0.0",
|
||||
"@alfresco/js-api": "10.0.0",
|
||||
"@angular/core": "20.3.25",
|
||||
"@angular/material": "20.2.14",
|
||||
"@ngrx/store": "~20.1.0",
|
||||
"typescript": "5.9.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The whole `@angular/*` toolchain moves to `20.x`, `@ngrx/*` to `~20.1.0`, `@angular-eslint/*` `19.8 → 20.7`,
|
||||
`@typescript-eslint/*` `→ 8.55.0`, `@nx/*` / `nx` `22 → 23`, `ng-packagr` `19 → 20`, `stylelint` `15 → 16`,
|
||||
`@mat-datetimepicker/core` `15 → 16`, and `@alfresco/adf-cli` / `@alfresco/eslint-plugin-eslint-angular` to `9.0.0`.
|
||||
The **`katex`, `mermaid`, `ngx-markdown` and `prismjs`** dependencies were **removed** (they backed the removed
|
||||
Knowledge Retrieval markdown rendering), and an `overrides` entry pins `node-fetch` for `@module-federation/sdk`.
|
||||
**Node is a patch bump** (`.nvmrc` `24.13.0 → 24.13.1`). Clean `node_modules` and the lockfile, then reinstall.
|
||||
|
||||
## Aligning with Angular 20 / ADF 9.0
|
||||
|
||||
See the ADF [8.5.0 → 9.0.0 guide](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade850-900.md)
|
||||
for the underlying platform detail.
|
||||
|
||||
### Angular 20 migration
|
||||
|
||||
ACA was lifted to Angular 20 (ACS-11306). Run the Angular 20 update
|
||||
(`ng update @angular/core@20 @angular/cli@20 @angular/material@20`) against your fork. Two notable points:
|
||||
|
||||
- **Built-in control flow adopted** — unlike the Angular 19 step, ACA now uses Angular's built-in control-flow
|
||||
syntax (`@if` / `@for`) in its templates. If your fork extends ACA templates, expect the new syntax.
|
||||
- **`inject()` DI** — the `@angular-eslint` `prefer-inject` rule (enabled in 7.4.1) is now the norm; constructor
|
||||
injection has largely been converted to `inject()`.
|
||||
|
||||
## Breaking changes
|
||||
|
||||
### Platform lockstep
|
||||
|
||||
You must move your application to **Angular 20, TypeScript 5.9 and NgRx 20** together with ACA. This is the
|
||||
dominant breaking change.
|
||||
|
||||
### Embedded Knowledge Retrieval removed
|
||||
|
||||
The embedded **Knowledge Retrieval (AI)** feature was **removed** from ACA (ACS-12037). All of its components were
|
||||
deleted — `agents-button`, `search-ai-input`, `search-ai-input-container`, `search-ai-results` and the
|
||||
`search-ai-marked-options` helper — along with the markdown rendering stack (`katex` / `mermaid` / `ngx-markdown` /
|
||||
`prismjs`).
|
||||
|
||||
In its place, ACA now offers a **link to an external Knowledge Discovery application**: a new
|
||||
`knowledge-discovery-sidenav` component navigates to the URL from the new **`knowledgeDiscoveryUrl`** app setting,
|
||||
which can be provided at runtime (e.g. via a Docker env var, #5295). If your fork depended on the in-app AI answer
|
||||
components or dispatched the AI search actions, migrate to the external Knowledge Discovery integration.
|
||||
|
||||
### Library public API
|
||||
|
||||
- **`@alfresco/aca-shared/store`** — **removed** the `search-ai.actions` and the `ai-search-by-term-payload` model
|
||||
(part of the Knowledge Retrieval removal above), and **added** `node-path.utils`.
|
||||
|
||||
`node-path.utils` exports a `NodeContentSource` type (`'personal-files' | 'libraries' | 'repository'`) and a
|
||||
`getNodeContentSource(path)` helper for determining which content source a node belongs to.
|
||||
|
||||
## New components and features
|
||||
|
||||
- **External Knowledge Discovery link** — the `knowledge-discovery-sidenav` component and the runtime-configurable
|
||||
`knowledgeDiscoveryUrl` app setting replace the removed in-app AI feature (ACS-12037 / #5295).
|
||||
- **`node-path.utils`** (`@alfresco/aca-shared/store`) — `NodeContentSource` / `getNodeContentSource()` for
|
||||
classifying a node's source (personal files, libraries or repository).
|
||||
- **Repository Access improvements** (MNT-25732) — enhancements to the repository-view feature introduced in 7.5.0.
|
||||
- **Search refactoring and unification** (MNT-25681), plus a debounce timer for saved searches that limits API
|
||||
calls on every keystroke (ACS-12041).
|
||||
|
||||
## Behavioural changes
|
||||
|
||||
| Area | Change |
|
||||
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Shared Files | Sorting now works for the Location, Size, Modified-by and Shared-by columns (ACS-12246). |
|
||||
| Bulk upload | The context menu no longer disappears during a bulk upload (ACS-11973), and the preview no longer switches to the next file (ACS-12047). |
|
||||
| Folder rules | Files can no longer be incorrectly marked as selected in the link-rules dialog (ACS-11975). |
|
||||
| Viewer | The image-viewer toolbar is no longer transparent in crop mode (ACS-12014). |
|
||||
| Search | The same term can be executed again when the search mode changes (#5297). |
|
||||
| Styling | Container elevation now uses a proper shadow rather than `box-shadow: none` (ACS-11879, an MD3 follow-up). |
|
||||
Reference in New Issue
Block a user