Updating an ADF project from version 1.5 to 1.6.1

[andraspopovics]

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.5 to version 1.6.1.

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:

1. Automatic update of the project using the Yeoman Generator.

2. 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.6.1.

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.5. You can find this example here (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.

1. The first step was the generation of an ADF project using the components  and alfresco-js-api version 1.5.

Nothing to describe here. In case of our planned modifications, you should have a similar project.

2. Fixing Typescript errors   (See this step in 1 commit here.)

1.6.1 components are using higher version of typescript than 1.5 does, so in order to avoid errors we have to use typescript version 2.3.4 at least.

After modification your package.json file should look like something like this:

"tslint": "^4.4.2",

"tslint-loader": "^3.3.0",

"typescript": "2.3.4",

"webpack": "^2.2.1",

"webpack-dev-server": "^2.3.0",

"webpack-merge": "^2.6.1",

3. Update Alfresco packages   (See this step in 1 commit here.)

Instead of using 1.5 packages, we want to use the latest 1.6.1 packages. For this we need to update all of the alfresco components and alfresco-js-api in the package.json.

"alfresco-js-api": "1.6.1",

"ng2-activiti-analytics": "1.6.1",

"ng2-activiti-diagrams": "1.6.1",

"ng2-activiti-form": "1.6.1",

"ng2-activiti-processlist": "1.6.1",

"ng2-activiti-tasklist": "1.6.1",

"ng2-alfresco-core": "1.6.1",

"ng2-alfresco-datatable": "1.6.1",

"ng2-alfresco-documentlist": "1.6.1",

"ng2-alfresco-login": "1.6.1",

"ng2-alfresco-search": "1.6.1",

"ng2-alfresco-tag": "1.6.1",

"ng2-alfresco-social": "1.6.1",

"ng2-alfresco-upload": "1.6.1",

"ng2-alfresco-userinfo": "1.6.1",

"ng2-alfresco-viewer": "1.6.1",

"ng2-alfresco-webscript": "1.6.1"

4. Material design   (See this step in 1 commit here.)

With our latest component upgrades we introduced Angular Material library as part of our ng2-alfresco-core package. At the moment we are using Angular Material and Material Design Lite side by side, but our goal is to remove the Material Design Lite package and just use the official one. To make it work we have to modify two files:

app/vendor.ts

Import one of the prebuilt themes from the node_modules:

import '@angular/material/prebuilt-themes/indigo-pink.css';

package.json

Update Angular Material version.

"@angular/router": "~4.0.0",

"@angular/compiler-cli": "~4.0.0",

"@angular/material": "2.0.0-beta.6",

"core-js": "2.4.1",

"reflect-metadata": "0.1.9",

"rxjs": "5.1.0",

5. Supporting new environment files   (See this step in 1 commit here.)

In the latest upgrade we extracted the environment settings description into different files. By default you have 2 settings files, one for the production environment (app.config-prod.json) and one for the development environment (app.config-dev.json). Both of them shares the same basic scheme, which is the following by default:

{
    "ecmHost": "http://localhost:3000/ecm",
    "bpmHost": "http://localhost:3000/bpm",
    "application": {
        "name": "Alfresco"
    }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

In order for these files to take effect, you have to tell your module which file is to use. You can do it in your app.module.ts, like this:

...
let appConfigFile = 'app.config-dev.json';
if (process.env.ENV === 'production') {
    appConfigFile = 'app.config-prod.json';
}

@NgModule({
    imports: [
        ...
        CoreModule.forRoot({
            appConfigFile: appConfigFile
        }),
        ...
});
...‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

These new files have to be served by your webpack, so you have to add them to your Webpack copy plugin in config/webpack.common.js file:

...    
    new CopyWebpackPlugin([
      ...
      {
          from: 'app.config-dev.json'
      },
      {
          from: 'app.config-prod.json'
      },      
      ...
    ]),
...‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

As a last step you should modify you SettingComponent (usually located in app/components/setting/setting.component.ts)

export class SettingComponent implements AfterViewChecked {

    ecmHost: string;
    bpmHost: string;

    constructor(private settingsService: AlfrescoSettingsService,
                private storage: StorageService,
                private logService: LogService) {
        this.ecmHost = storage.getItem('ecmHost') || this.settingsService.ecmHost;
        this.bpmHost = storage.getItem('bpmHost') || this.settingsService.bpmHost;        
    }

    ngAfterViewChecked() {
        // workaround for MDL issues with dynamic components
        if (componentHandler) {
            componentHandler.upgradeAllRegistered();
        }
    }

    public onChangeECMHost(event: KeyboardEvent): void {
        let value = (<HTMLInputElement>event.target).value.trim();
        if (value && this.isValidUrl(value)) {
            this.logService.info(`ECM host: ${value}`);
            this.ecmHost = value;
            this.storage.setItem(`ecmHost`, value);
        } else {
            console.error('Ecm address does not match the pattern');
        }
    }

    public onChangeBPMHost(event: KeyboardEvent): void {
        let value = (<HTMLInputElement>event.target).value.trim();
        if (value && this.isValidUrl(value)) {
            this.logService.info(`BPM host: ${value}`);
            this.bpmHost = value;
            this.storage.setItem(`bpmHost`, value);
        } else {
            console.error('Bpm address does not match the pattern');
        }
    }

    isValidUrl(url: string) {
        return /^(http|https):\/\/.*/.test(url);
    }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

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.