From b233d071a8618e10bcc0a5214a19beb1c5cfe26f Mon Sep 17 00:00:00 2001 From: Denys Vuika Date: Wed, 26 Apr 2023 08:56:00 -0400 Subject: [PATCH] refine upgrade to 6.0.0 guide (#8514) * refine upgrade to 6.0.0 guide * minor fixes --- docs/upgrade-guide/upgrade50-60.md | 303 ++++++++++++++++------------- 1 file changed, 163 insertions(+), 140 deletions(-) diff --git a/docs/upgrade-guide/upgrade50-60.md b/docs/upgrade-guide/upgrade50-60.md index 3724436334..137f7e01fc 100644 --- a/docs/upgrade-guide/upgrade50-60.md +++ b/docs/upgrade-guide/upgrade50-60.md @@ -4,95 +4,93 @@ Title: Upgrading from ADF v5.0 to v6.0 # Upgrading from ADF v5.0 to v6.0 -This guide explains how to upgrade your ADF v5.0 project to work with v6.0. +This guide provides instructions on how to upgrade your v5.0.0 ADF projects to v6.0.0. -Do not skip this task, if you want your application to be updated to a most recent version of ADF. Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates. +**Warning**: Be sure to follow the guide below to migrate your application to the new version. +You can't update Angular and ADF applications more than one major version at a time. -**Note:** the steps described below might involve making significant changes -to your code. If you are working with a versioning system then you should -commit any changes you are currently working on. If you aren't using versioning -then be sure to make a backup copy of your project before going ahead with the -upgrade. +## Before you begin -Since 6.0 is a major version release, there are [breaking changes](#breaking-changes) -you need to take into account as well as the usual library updates. After updating -the libraries, check the other sections to see if any of the changes affect your -project. +Always perform upgrades on "clean" project state, backup your changes or make a project backup. + +Since 6.0.0 is a major version release, there are [breaking changes](#breaking-changes) +you need to take into account as well as the usual library updates. + +After the upgrade, check other sections to see if there are any changes affecting your project. ## Contents -- [Library updates](#library-updates) -- [Breaking changes](#breaking-changes) -- [Library to update](#library-to-update) -- [Deprecated items](#deprecated-items) - - [DataColumnModule](#datacolumnmodule) - - [PaginationModel](#paginationmodel) -- [Relocated classes](#relocated-classes) - - [Update Data-table a data change](#update-data-table-a-data-change) - - [NodeNameTooltipPipe](#nodenametooltippipe) - - [nodeUpdated Subject](#nodeupdated-subject) - - [Comments component](#comments-component) - - [ViewerComponent](#viewercomponent) - - [UserInfoComponent](#userinfocomponent) -- [Renamed items](#renamed-items) - - [New Classes or Services](#new-classes-or-services) - - [Properties and methods](#properties-and-methods) - - [Component selectors](#component-selectors) -- [Theme changes](#theme-changes) +- [Library updates](#library-updates) +- [Breaking changes](#breaking-changes) +- [Library to update](#library-to-update) +- [Deprecated items](#deprecated-items) + - [DataColumnModule](#datacolumnmodule) + - [PaginationModel](#paginationmodel) +- [Relocated classes](#relocated-classes) + - [Update Data-table a data change](#update-data-table-a-data-change) + - [NodeNameTooltipPipe](#nodenametooltippipe) + - [nodeUpdated Subject](#nodeupdated-subject) + - [Comments component](#comments-component) + - [ViewerComponent](#viewercomponent) + - [UserInfoComponent](#userinfocomponent) +- [Renamed items](#renamed-items) + - [New Classes or Services](#new-classes-or-services) + - [Properties and methods](#properties-and-methods) + - [Component selectors](#component-selectors) +- [Theme changes](#theme-changes) ## Library updates -1. Update the `package.json` file with the latest library versions: +Update the `package.json` file with the latest library versions: - ```json +```json +{ "dependencies": { - ... "@alfresco/adf-core": "6.0.0", "@alfresco/adf-content-services": "6.0.0", "@alfresco/adf-process-services-cloud": "6.0.0", "@alfresco/adf-insights": "6.0.0", - "@alfresco/js-api": "6.0.0", - ... - ``` + "@alfresco/js-api": "6.0.0" + } +} +``` -2. Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`. +Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`. -3. Reinstall your dependencies - ```sh - npm install - ``` +Reinstall your dependencies + +```sh +npm install +``` ## Breaking changes -The ADF project follows the [semver](https://semver.org/) conventions and so we -only make breaking changes (ie, not backward-compatible) in _major_ versions. -ADF 6.0 is the first major version since general availability so a number of +The ADF project follows the [semver](https://semver.org/) conventions, +breaking changes are introduced in _major_ versions. + +ADF 6.0.0 is the first major version since general availability so a number of deprecated items have been removed and also some existing items have been renamed. The sections below explain how to adapt your project to the changes -in 6.0. See also our -For more information about the changes and links to the associated -pull requests. +coming with 6.0.0 release. -[TODO ADD HERE the PRs ][`checkallowableoperationdirective`](../content-services/directives/check-allowable-operation.directive.md): Moved from ADF Core to ADF content services -[`LibraryFavoriteDirective`](../../lib/content-services/src/lib/directives/library-favorite.directive.ts): Moved from ADF Core to ADF content services -[`LibraryMembershipDirective`](../../lib/content-services/src/lib/directives/library-membership.directive.ts): Moved from ADF Core to ADF content services -[`NodeDeleteDirective`](../content-services/directives/node-delete.directive.md): Moved from ADF Core to ADF content services -[`NodeFavoriteDirective`](../content-services/directives/node-favorite.directive.md): Moved from ADF Core to ADF content services -[`NodeRestoreDirective`](../content-services/directives/node-restore.directive.md): Moved from ADF Core to ADF content services -[TODO ADD HERE the PRs ] +## Directives -Each section needs to contains: -Title -Description -How to fix it: +| Name | Description | +| --- | --- | +| [`CheckAllowableOperationDirective`](../content-services/directives/check-allowable-operation.directive.md)| Moved from ADF Core to ADF content services | +| [`LibraryFavoriteDirective`](../../lib/content-services/src/lib/directives/library-favorite.directive.ts) | Moved from ADF Core to ADF content services | +| [`LibraryMembershipDirective`](../../lib/content-services/src/lib/directives/library-membership.directive.ts) | Moved from ADF Core to ADF content services | +| [`NodeDeleteDirective`](../content-services/directives/node-delete.directive.md) | Moved from ADF Core to ADF content services | +| [`NodeFavoriteDirective`](../content-services/directives/node-favorite.directive.md) | Moved from ADF Core to ADF content services | +| [`NodeRestoreDirective`](../content-services/directives/node-restore.directive.md) | Moved from ADF Core to ADF content services | -## Library to update +## Third-party Libraries | Name | Version | | ---- | ------- | | `pdfjs-dist` | `3.3.122` | -## Deprecated items +## Deprecated Items | Class | Before | Description | | ----- | ------ | ----------- | @@ -106,28 +104,32 @@ How to fix it: [`DataColumnModule`](../../lib/core/src/lib/datatable/data-column/data-column.module.ts) has been deprecated and moved in [`DataTableModule`](../../lib/core/src/lib/datatable/datatable.module.ts) -v6.0.0 and before: +Before: - @NgModule({ - imports: [ - ``` +```ts +@NgModule({ + imports: [ DataColumnModule, DataTableModule - ``` - ]) + ] +}) +export class MyModule {} +``` -v6.0.0 and after: +After: - @NgModule({ - imports: [ - ``` +```ts +@NgModule({ + imports: [ DataTableModule, - ``` - ]) + ] +}) +export class MyModule {} +``` ### PaginationModel -`Pagination` model from `@alfresco/js-api` has been now deprecated in favour of internal implementated model [`PaginationModel`](../../lib/core/src/lib/models/pagination.model.ts) evrywhere +`Pagination` model from `@alfresco/js-api` has been now deprecated in favour of ADF model [`PaginationModel`](../../lib/core/src/lib/models/pagination.model.ts). ## Relocated classes @@ -145,7 +147,6 @@ v6.0.0 and after: | [`NodeFavoriteDirective`](../content-services/directives/node-favorite.directive.md) | `@alfresco/adf-core` | `@alfresco/adf-content-services` | | [`NodeRestoreDirective`](../content-services/directives/node-restore.directive.md) | `@alfresco/adf-core` | `@alfresco/adf-content-services` | | [`NodeDownloadDirective`](../core/directives/node-download.directive.md) | `@alfresco/adf-core` | `@alfresco/adf-content-services` | -| [`AppsProcessService`] | `@alfresco/adf-core` | `@alfresco/adf-process-services` | | [`SharedLinksApiService`](../core/services/shared-links-api.service.md) | `@alfresco/adf-core` | `@alfresco/adf-process-services` | | [`LockService`](../../lib/content-services/src/lib/document-list/services/lock.service.ts) | `@alfresco/adf-core` | `@alfresco/adf-process-services` | | [`FavoritesApiService`](../core/services/favorites-api.service.md) | `@alfresco/adf-core` | `@alfresco/adf-process-services` | @@ -172,25 +173,30 @@ v6.0.0 and after: | [`NodeMetadata`](../../lib/content-services/src/lib/common/models/node-metadata.model.ts) | `@alfresco/adf-core` | `@alfresco/adf-content-services` | | [`RichTextEditorComponent`](../../lib/process-services-cloud/src/lib/rich-text-editor/rich-text-editor.component.ts) | `@alfresco/adf-core` | `@alfresco/adf-process-services-cloud` | -### Update Data-table a data change +### DataTable changes -v6.0.0 and after You will need to provide a [`DataTableService`](../../lib/core/src/lib/datatable/services/datatable.service.ts) to update a row of your table. -The model to update the DataTable require the ID of the row you want change and the new data Object of the row +Starting with v6.0.0, you need to provide a [`DataTableService`](../../lib/core/src/lib/datatable/services/datatable.service.ts) to update a row of your table. +The model to update the DataTable require the `id` of the row that is being changed, and the new data Object of the row: ```typescript -DataRowUpdateModel { +interface DataRowUpdateModel { obj: any; id: string; } ``` -For example if your table use entry nodes you can pass: +For example, if your table use entry nodes you can pass: ```typescript -this.dataTableService.rowUpdate.next({id: node.id, obj: {entry: node}}); +this.dataTableService.rowUpdate.next({ + id: node.id, + obj: { + entry: node + } +}); ``` -As good practice is better to provide a [`DataTableService`](../../lib/core/src/lib/datatable/services/datatable.service.ts) in the component where you are going to deliver the new object +As good practice, it is suggested to provide a [`DataTableService`](../../lib/core/src/lib/datatable/services/datatable.service.ts) at the component level: ```typescript @Component({ @@ -203,118 +209,135 @@ As good practice is better to provide a [`DataTableService`](../../lib/core/src/ ] }) export class FilesComponent implements OnInit { - constructor(private dataTableService: DataTableService, private nodeService: NodesApiService) { } ngOnInit() { this.nodeService.nodeUpdated.subscribe((node) => { - this.dataTableService.rowUpdate.next({id: node.id, obj: {entry: node}}); + this.dataTableService.rowUpdate.next({ + id: node.id, + obj: { + entry: node + } + }); }); } +} ``` ### NodeNameTooltipPipe -[`NodeNameTooltipPipe`](../core/pipes/node-name-tooltip.pipe.md) has been moved in the `@alfresco/adf-content-services` in [`ContentPipeModule`](../../lib/content-services/src/lib/pipes/content-pipe.module.ts) +[`NodeNameTooltipPipe`](../core/pipes/node-name-tooltip.pipe.md) has been moved to the `@alfresco/adf-content-services` into the [`ContentPipeModule`](../../lib/content-services/src/lib/pipes/content-pipe.module.ts) -v6.0.0 and before: +Before: - @NgModule({ - imports: [ - ```` +```ts +@NgModule({ + imports: [ PipeModule - ```` - ]}) + ] +}) +export class MyModule {} +``` -v6.0.0 and after: +After: - @NgModule({ - imports: [ - ```` +```ts +@NgModule({ + imports: [ ContentPipeModule - ```` - ]}) + ] +}) +export class MyModule {} +``` ### nodeUpdated Subject -The nodeUpdated [`Subject`](http://reactivex.io/documentation/subject.html) has been moved from [`AlfrescoApiService`](../core/services/alfresco-api.service.md) to [`NodesApiService`](../core/services/nodes-api.service.md) +The `nodeUpdated` [`Subject`](http://reactivex.io/documentation/subject.html) has been moved from [`AlfrescoApiService`](../core/services/alfresco-api.service.md) to [`NodesApiService`](../core/services/nodes-api.service.md) -v6.0.0 and before: +Before: - this.alfrescoApiService.nodeUpdated.pipe ..... +```ts +this.alfrescoApiService.nodeUpdated.pipe(...).subscribe(...); +``` -v6.0.0 and after: +After: - this.nodesApiService.nodeUpdated.pipe ..... +```ts +this.nodesApiService.nodeUpdated.pipe(...).subscribe(...); +``` ### Comments component -`adf-comments` component is now a real presentational components. The `taskId` and `nodeId` has now renamed to `id` +`adf-comments` component is now a presentational components. The `taskId` and `nodeId` has been merged and moved to the `id` property. + The `adf-comments` has now two specialization in : -- `adf-node-comments` [Node Comments Componen](../content-services/components/node-comments.component.md) -- `adf-task-comments` [Task Comments Component](../process-services/components/task-comments.component.md) +- `adf-node-comments` [Node Comments Component](../content-services/components/node-comments.component.md) +- `adf-task-comments` [Task Comments Component](../process-services/components/task-comments.component.md) ### ViewerComponent -From v.6.0.0 and after [`ViewerComponent`](../core/components/viewer.component.md) no longer show content from ACS, so instead of taking `nodeId` as `@Input`, it takes `blobFile` and `urlFile`. For more details check the [`PR`](https://github.com/Alfresco/alfresco-ng2-components/pull/7992). +The [`ViewerComponent`](../core/components/viewer.component.md) no longer shows content from ACS, so instead of taking `nodeId` as `@Input`, it takes `blobFile` and `urlFile`. + +For more details check the [`PR`](https://github.com/Alfresco/alfresco-ng2-components/pull/7992). If you need to display content from ACS you can use instead the new [`AlfrescoViewerComponent`](../content-services/components/alfresco-viewer.component.md) ### UserInfoComponent -From v.6.0.0 and after [`UserInfoComponent`](../../lib/core/src/lib/userinfo/components/user-info.component.ts) is no longer active. +The [`UserInfoComponent`](../../lib/core/src/lib/userinfo/components/user-info.component.ts) is no longer active. In its place there are now 3 presentational components: -- [`IdentityUserInfoComponent`](../core/components/identity-user-info.component.md) present in core -- [`ContentUserInfoComponent`](../content-services/components/content-user-info.component.md) present in content-services -- [`ProcessUserInfoComponent`](../process-services/components/process-user-info.component.md) present in process-services +- [`IdentityUserInfoComponent`](../core/components/identity-user-info.component.md) (Core) +- [`ContentUserInfoComponent`](../content-services/components/content-user-info.component.md) (Content Services) +- [`ProcessUserInfoComponent`](../process-services/components/process-user-info.component.md) (Process Services) -To build a similar logic to the one in [`UserInfoComponent`](../../lib/core/src/lib/userinfo/components/user-info.component.ts) check implementation on [`demo-shell`](../../demo-shell/src/app/components/app-layout/user-info/user-info.component.ts) +To build a similar logic to the one in [`UserInfoComponent`](../../lib/core/src/lib/userinfo/components/user-info.component.ts), check example implementation in [`demo-shell`](../../demo-shell/src/app/components/app-layout/user-info/user-info.component.ts). ## Renamed items ### New Classes or Services -- [`AlfrescoViewerComponent`](../content-services/components/alfresco-viewer.component.md) -- [`ViewerRenderComponent`](../core/components/viewer-render.component.md) - -### Properties and methods - -### Component selectors +- [`AlfrescoViewerComponent`](../content-services/components/alfresco-viewer.component.md) +- [`ViewerRenderComponent`](../core/components/viewer-render.component.md) ## Theme changes -v6.0.0 has improved the way that typography is injected into the ADF theme. Now the typography of ADF is taken from the material theme following the material design specifications : +v6.0.0 has improved the way that typography is injected into the ADF theme. Now the typography of ADF is taken from the Material Theme following the Material design specifications. -before v6.0.0 +Before: - @include mat-core($typography); - $primary: mat.define-palette($primary); - $accent: mat.define-palette($accent); - $warn: mat.define-palette($warn); - $theme: mat-light-theme($primary, $accent, $warn); +```scss +@include mat-core($typography); -typography was already predefined inside ADF theme but this will prevent to inject different typography. +$primary: mat.define-palette($primary); +$accent: mat.define-palette($accent); +$warn: mat.define-palette($warn); +$theme: mat-light-theme($primary, $accent, $warn); +``` -v6.0.0 and after +The typography was already predefined inside ADF theme but this prevents customisations. - $typography: mat.define-typography-config( - ...define your typography following material specifications - ); +After: - $primary: mat.define-palette($primary); - $accent: mat.define-palette($accent); - $warn: mat.define-palette($warn); - $theme: mat.define-light-theme( - ( - color: ( - primary: $primary, - accent: $accent, - warn: $warn - ), - typography: $typography - ) - ); +```scss +$typography: mat.define-typography-config( + // ...define your typography following material specifications +); + +$primary: mat.define-palette($primary); +$accent: mat.define-palette($accent); +$warn: mat.define-palette($warn); +$theme: mat.define-light-theme( + ( + color: ( + primary: $primary, + accent: $accent, + warn: $warn + ), + typography: $typography + ) +); +```