In this Tutorial, I would like to help you to update your project created with the ADF Yeoman app generator. Many people have asked on our gitter channel which are the correct steps to upgade from version 1.7 to version 1.8.
In order to understand the possible ways to update a project I did some different experiments with old projects and I finally find out the following two different approaches:
Automatic update of the project using the Yeoman Generator.
Manually update the project.
If you are not using a versioning system on your project I suggest you to execute backup copy of it before to following one of this approach.
1. Automatic update of the project using the Yeoman Generator
If your application is mainly just the output of the generated app, you can try to follow those steps:
- Update the Yeoman generator to version 1.8.
npm uninstall -g generator-ng2-alfresco-app
npm install -g generator-ng2-alfresco-app
- Run the new yeoman app generator.
yo ng2-alfresco-app
- Clean your old distribution and dependencies.
npm run clean
- Install the dependencies.
npm install
At this point, the generator could have maybe overwritten some of your changes. Remember to check the differences with the original source code (this is one of the reasons you should use a versioning system) and, if this is the case, retrofit the changes. Once done, it's time to start the application using the npm run start command.
After starting the app, if everything is working fine, that's all and you don't need to do anything else. On the contrary, if you have bugs and nothing really work, recover the original version of the project and try the manual approach.
2. Manually update the project
Considering that a project generated using the scaffolder is probably customised, its automatic update could not be an option. The following method is more surgical and would request a bit of elbow grease. As an example, I created a new project with the Yeoman generator version 1.7. You can find this example in the folder belonging to the 1.8 update in the ADF examples repo. As you can see, each commit represents a separate step in the upgrade process, which I now describe one by one.
The components v1.8.0 use Angular v4.2.5 (the latest at the time of writing), so please be sure to update your Angular modules to the latest as a prerequisite step. This includes every module of Angular.
1. The first step was the generation of an ADF project using the components and alfresco-js-api version 1.7.
Nothing to describe here. In case of our planned modifications, you should have a similar project.
2. Material design
In this month the Material design package has been updated, and got a new version, but we haven't updated our packages to use the latest version of it yet. Because of this, you have to be sure, that you are using the correct version of Material, otherwise you will get mystical errors. The right version is 2.0.0-beta.8. If you happen to have a caret or tilde in your semversion, remove it.
package.json
Update Angular Material version.
| "@angular/router": "~4.0.0", |
| "@angular/compiler-cli": "~4.0.0", |
| "@angular/material": "2.0.0-beta.8", |
| "@angular/cdk": "2.0.0-beta.8", |
| "core-js": "2.4.1", |
| "reflect-metadata": "0.1.9", |
| "rxjs": "5.1.0", |
3. Update Alfresco packages
Instead of using 1.7 packages, we want to use the latest 1.8 packages. For this we need to update all of the alfresco components and alfresco-js-api in the package.json.
| "alfresco-js-api": "1.8.0", |
| "ng2-activiti-analytics": "1.8.0", |
| "ng2-activiti-diagrams": "1.8.0", |
| "ng2-activiti-form": "1.8.0", |
| "ng2-activiti-processlist": "1.8.0", |
| "ng2-activiti-tasklist": "1.8.0", |
| "ng2-alfresco-core": "1.8.0", |
| "ng2-alfresco-datatable": "1.8.0", |
| "ng2-alfresco-documentlist": "1.8.0", |
| "ng2-alfresco-login": "1.8.0", |
| "ng2-alfresco-search": "1.8.0", |
| "ng2-alfresco-tag": "1.8.0", |
| "ng2-alfresco-social": "1.8.0", |
| "ng2-alfresco-upload": "1.8.0", |
| "ng2-alfresco-userinfo": "1.8.0", |
| "ng2-alfresco-viewer": "1.8.0", |
| "ng2-alfresco-webscript": "1.8.0" |
4. Fix changed component errors
There are some components in this release which interface has been changed, so you have to modify your application to work properly.
ng2-alfresco-userinfo
In your app/app.component.html file remove the [menuOpenType]="left" since this @Input property has been removed. Use the one below:
<div>
<ng2-alfresco-userinfo class="user-profile" [menuPositionX]="after" [menuPositionY]="below">
</ng2-alfresco-userinfo>
</div>
adf-document-list
In your app/components/files/files.component.html file remove the [creationMenuActions]="!useCustomToolbar" since this @Input property has been removed.
<adf-document-list
#documentList
[permissionsStyle]="permissionsStyle"
[currentFolderId]="currentFolderId"
[contextMenuActions]="true"
[contentActions]="true"
[allowDropFiles]="true"
[selectionMode]="selectionMode"
[multiselect]="multiselect"
(error)="onNavigationError($event)"
(success)="resetError()"
(preview)="showFile($event)"
(permissionError)="handlePermissionError($event)">
...
5. Use one of the prebuilt Alfresco themes (or create a custom for yourself, for more info, check the documentation)
By default, you can choose from the prebuilt Alfresco themes defined below:
- adf-blue-orange.css
- adf-blue-purple.css
- adf-cyan-orange.css
- adf-cyan-purple.css
- adf-green-orange.css
- adf-green-purple.css
- adf-indigo-pink.css
- adf-pink-bluegrey.css
- adf-purple-green.css
In your app/vendor.ts file add the following line of code:
import 'ng2-alfresco-core/prebuilt-themes/adf-blue-orange.css';
After all these changes, it is suggested to execute the following commands.
- Clean your old distribution and dependencies.
npm run clean
- Install the dependencies.
npm install
That's all! Now you can start again your project, as usual using npm run start.
If everything is working fine: well done! You project is correctly updated to the new ADF version.
If not, feel free to reply here or contact us on gitter or raising a question in the Application Development Framework space.
