mirror of https://github.com/Alfresco/alfresco-content-app.git synced 2026-09-09 18:02:54 +00:00

Files

T

Michal Kinas c05c193195 [ACS-12451] Add missing upgrade guides in ACA (#5345 )

* [ACS-12451] Add missing upgrade guides in ACA

* [ACS-12451] CR fix

2026-08-12 14:10:24 +02:00

11 KiB

Raw Permalink Blame History

Title

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:

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 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.)

Library updates
Aligning with ADF 6.1 / 6.2
Breaking changes
New components and features
Behavioural changes

Library updates

Update the package.json file with the latest library versions:

{
    "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):

// 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-ids 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.

11 KiB Raw Permalink Blame History