This guide explains how to upgrade your ADF v2.6 project to work with v3.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.
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.
Since 3.0 is a major version release, there are 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.
If your application has few changes from the original app created by the Yeoman generator then you may be able to update your project with the following steps:
Update the Yeoman generator to the latest version (3.0.0). Note that
you might need to run these commands with sudo
on Linux or MacOS:
npm uninstall -g generator-alfresco-adf-app npm install -g generator-alfresco-adf-app
Run the new yeoman app generator:
yo alfresco-adf-app
Clean your old distribution and dependencies by deleting the node_modules
folder
and the package-lock.json
file.
Install the dependencies:
npm install
At this point, the generator might have overwritten some of your code where it differs from the original generated app. Be sure to check for any differences from your project code (using a versioning system might make this easier) and if there are any differences, retrofit your changes. When you have done this, you should be able to start the application as usual:
npm run start
After starting the app, if everything is working fine, that's all and you don't need to do anything else. However, if things don't work as they should then recover the original version of the project and try the manual approach.
Update the package.json
file with the latest library versions:
"dependencies": {
...
"@alfresco/adf-core": "3.0.0",
"@alfresco/adf-content-services": "3.0.0",
"@alfresco/adf-process-services-cloud": "3.0.0",
"@alfresco/adf-insights": "3.0.0",
"@alfresco/js-api": "3.0.0",
...
Clean your old distribution and dependencies by deleting node_modules
and package-lock.json
.
Reinstall your dependencies
npm install
The ADF project follows the semver conventions and so we only make breaking changes (ie, not backward-compatible) in major versions. ADF 3.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 3.0. See also our breaking changes document for more information about the changes and links to the associated pull requests.
The name package of the JS-API has been modified to use the @alfresco
namespace and so
you should change all alfresco-js-api
imports to @alfresco/js-api
.
See the
JS-API documentation
for more details on how to use the new v3.0.0
Legacy Endpoint porting.
Also, the JS-API callApi
method signature has been modified. The authNames
parameter has been removed because the type of authentication is configured
when the JS-API is constructed. You should remove references to authNames
from your code.
v2.6.1 and before:
callApi( path: string, httpMethod: string, pathParams?: any, queryParams?: any, headerParams?: any, formParams?: any, bodyParam?: any, authNames?: string[], contentTypes?: string[], accepts?: string[], returnType?: any, contextRoot?: string, responseType?: string ): Promise<any>;
After v3.0.0:
callApi( path: string, httpMethod: string, pathParams?: any, queryParams?: any, headerParams?: any, formParams?: any, bodyParam?: any, contentTypes?: string[], accepts?: string[], returnType?: any, contextRoot?: string, responseType?: string ): Promise<any>;
The hasPermission
method in the ContentService
was found to be actually checking the allowableOperation
value. To reflect this,
the method has been renamed as hasAllowableOperations
and a new hasPermission
method has been added (this one checks the permissions correctly as expected).
If you were using the old hasPermission
method successfully in v2.6 then you should
update your code to use hasAllowableOperations
, which has the same behavior. If your
code was having problems with the earlier incorrect behavior of hasPermission
then
you should find it now works correctly.
Related to this issue is the hasPermission
method of the
Document List Service which has been
made redundant by
ContentService
.hasAllowableOperations
and has now been removed.
Also, the former Node
Permission Directive has now been renamed as the
Check Allowable Operation directive
to better reflect its true behavior. You should therefore replace existing references to
adf-node-permission
with adf-check-allowable-operation
.
The deprecated items listed below have been removed from ADF as of v3.0. You should update your code to use the suggested fix for each item that affects your project.
The adf-accordion
and adf-accordion-group
components have been removed.
Replace instances of these components with the Angular
mat-accordion
component. See the
mat-expansion-panel
doc page for an example of how to do this.
Viewer component: The allowShare
input has been removed. Inject the
Share Directive in a
custom toolbar to recreate the behavior of the Share button.
Viewer component: The handling of the sidebar has been updated to allow left and right sidebars at the same time. The following properties have changed, so you should update your code to use the new properties:
allowSidebar
input has now been split into allowLeftSidebar
and allowRightSidebar
.showSidebar
input has now been split into showLeftSidebar
and showRightSidebar
.sidebarTemplate
input has now been split into sidebarLeftTemplate
and
sidebarRightTemplate
.sidebarPosition
input has been removed (the other new inputs render it obsolete).The createFolder
event of the UploadBase
class (emitted when a folder was created) has been removed. You should modify your code to use the success
event instead.
Login component: Two inputs have been removed: disableCsrf
and providers
. Set the
properties with the same names in app.config.json
to get the same effect.
File Draggable Directive: The file-draggable
event has been removed.
Use filesDropped
instead to get the same effect.
Search control component: The QueryBody
, and
customQueryBody
inputs of the SearchControlComponent
have been removed. See the
Search configuration interface
page to learn how to get the same functionality.
Document list component: Several inputs have been removed or replaced:
skipCount
input has been removed. You can define
the same value in pagination using the pageSize
property.enableInfiniteScrolling
input has been removed. To choose the pagination strategy, add either the
Infinite Pagination Component or the normal Pagination Component and assign
your document list as the target
.folderNode
input has been removed. Use the currentFolderId
and node
inputs
instead.The SettingsService
class has been removed. Access the equivalent properties with the
App config service
Form service: the addFieldsToAForm
method has been removed.
The following classes have been moved from their original libraries to the Core
library. You should modify your code to import these classes from
@alfresco/adf-core
.
DownloadZipDialogComponent
(formerly Content Services)NodeDownloadDirective
(formerly Content Services)CommentsModule
(formerly Process Services)CommentListComponent
(formerly Process Services)CommentsComponent
(formerly Process Services)Also, CommentProcessModel
was moved from Process Services to Core and renamed as CommentModel
. You should update both the name of the class and the import line in your code.
The items listed below have been renamed (the old names have been deprecated for some time but have now been removed). If your code refers to the old names then you should replace them with the new ones.
CommentProcessModel
was moved from Process Services to Core and renamed as CommentModel
<adf-form>
: The onError
event has now been renamed as error
.<adf-viewer>
: The fileNodeId
input that supplies the Node
Id of the file to
load has been renamed as nodeId
.<adf-upload-drag-area>
: The parentId
input has been renamed as rootFolderId
.adf-filters
is now adf-task-filters
.adf-node-permission
is now adf-check-allowable-operation
.analytics-report-list
is now adf-analytics-report-list
.analytics-report-parameters
is now adf-analytics-report-parameters
.context-menu-holder
is now adf-context-menu-holder
.diagram-alfresco-publish-task
is now adf-diagram-publish-task
.diagram-sequence-flow
is now adf-diagram-sequence-flow
.file-uploading-dialog
is now adf-file-uploading-dialog
.A new style linting rule requires all CSS classes defined by ADF to have the prefix
adf-
. If you use modified versions of these classes then you will need to add the
adf-
prefix to the appropriate class names for them to be recognised.
The names of the changed classes are listed below according to the file in which
they are defined. The new form of the name (ie, with the adf-
prefix added) is
listed but there are a few exceptions where the names were also altered in other ways.
These changes are noted with an arrow "->".
adf-isRoot
adf-focus
adf-active
adf-search-results-label
adf-dropdown-breadcrumb-item-chevron
adf-choose-action
adf-choose-action
adf-input-action
adf-full-width
adf-spacer
adf-document-list_empty_template
adf-document-list__this-space-is-empty
adf-document-list__drag-drop
adf-document-list__any-files-here-to-add
adf-document-list__empty_doc_lib
adf-cell-container
adf-cell-value
adf-facet-filter
adf-facet-name
adf-highlight
adf-checklist
adf-facet-label
adf-facet-result-filter
adf-facet-buttons
adf-facet-filter
adf-filter-label
adf-full-width
adf-upload-dialog
adf-upload-dialog__content
adf-upload-new-version
adf-about-container
adf-material-icons
adf-card-view
adf-is-selected
adf-is-selected
alfresco-datatable__actions-cell
-> adf-datatable__actions-cell
adf-image-table-cell
adf-cell-container
adf-no-select
adf-sortable
adf-cell-value
adf-full-width
adf-ellipsis-cell
adf-sr-only
adf-hidden
adf-desktop-only
adf-debug-toggle-text
adf-invalid-color
adf-hidden
adf-container-widget__header-text
adf-collapsible
adf-grid-list
adf-grid-list-item
adf-is-selected
adf-no-select
adf-sortable
adf-full-width
adf-sidenav--hidden
adf-sidenav-layout
adf-layout__content
adf-copyright
adf-ie11FixerParent
adf-ie11FixerChild
adf-show
adf-hide
adf-icon-inline
adf-error-icon
adf-isChecking
adf-isWelcome
adf-welcome-icon
adf-login-checking-spinner
adf-is-active
adf-copyright
adf-login-rememberme
-> - adf-login-remember-me
adf-full-width
adf-image-container
adf-pdf-thumbnails
adf-loader-container
adf-thumbnails-template
adf-loader-item
adf-highlight
adf-begin
adf-end
adf-middle
adf-selected
adf-endOfContent
adf-active
adf-annotationLayer
adf-linkAnnotation
adf-textAnnotation
adf-popupWrapper
adf-popup
adf-highlightAnnotation
adf-underlineAnnotation
adf-squigglyAnnotation
adf-strikeoutAnnotation
adf-fileAttachmentAnnotation
adf-pdfViewer
adf-page
adf-loadingIcon
adf-removePageBorders
adf-hidden
adf-viewer-pdf-viewer
adf-full-screen
adf-info-drawer-content
adf-chart
adf-analytics-row__entry
adf-report-icons
adf-full-width
adf-partial-width
adf-clear-both
adf-activiti-filters__entry
adf-activiti-filters__entry-icon
adf-activiti-filters__label
adf-active
adf-application-title
adf-dropdown-widget
adf-dropdown-widget__select
adf-dropdown-widget__invalid
adf-dropdown-widget__label
adf-is-hide
adf-report-container-setting
adf-option_button_details
adf-export-message
adf-save-export-input
adf-delete-parameter
adf-hide
adf-chart
adf-dropdown-container
adf-is-active
adf-line-clamp
adf-active
adf-no-content-message
adf-active
adf-line-clamp
adf-data-cell
adf-data-cell
adf-choose-action
adf-search-text-container
adf-search-list-container
adf-people-pic
adf-people-img
adf-activiti-label
adf-fix-element-user-list
adf-search-text-header
adf-search-list-action-container
adf-assignment-header
adf-assignment-count
adf-add-people
adf-assignment-top-container
adf-assignment-top-container-content
adf-assignment-container
adf-assignment-list-container
adf-cell-container
adf-people-email
adf-people-img
adf-activiti-label
adf-icon
adf-list-wrap
adf-hide-long-names
adf-active
adf-activiti-label
adf-checklist-menu-container
adf-checklist-none-message
activiti-label
-> adfactiviti-label
adf-people-widget-content
adf-error-dialog
adf-activiti-task-details__header
adf-activiti-task-details__action-button
adf-assignment-container
adf-task-header
adf-assign-edit-view
adf-property
adf-active
© 2023 Alfresco Software, Inc. All Rights Reserved.
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.