Upgrading from version 1.x

The version 1.x of HSLayers-NG was built using AngularJS framework. Version 2.x is using a more modern and newer Angular framework. Although these two are direct successors, there are many differences between them.

In order to successfully upgrade your HSLayers-NG application from version 1.x to 2.x, you need to upgrade your AngularJS stuff to the new Angular. This pages provides a guide how to do it smoothly and painlessly.

Upgrade steps in recommended order

1. add TypeScript
2. replace AngularJS wrappers
3. rewrite all controllers to components
4. rewrite all services/providers to classes
5. upgrade hslayers-ng package
6. rewrite module definitions
7. rewrite components, services and templates

Introducing TypeScript

• Install TypeScript and its loader as a devDependency of yours npm i ng-annotate-loader ts-loader typescript@"^3.9.5" -D
• Create tsconfig.json
• Update your webpack.config.js with:

• • new entry point entry: { main: 'main.ts' },
• • new loader

        test: /\.ts$/,
        use: [
          { loader: 'ng-annotate-loader' },
          { loader: 'ts-loader', options: { allowTsInNodeModules: true }},
        ],
        exclude: /node_modules\/(?!(hslayers-ng)\/).*/,
      },

• • new extensions extensions: ['.ts', '.js'],
• • for html loading ng-cache-loader needs to be removed because it makes Angular 9 templates unusable and html-loader needs to be case sensitive not to lowercase angular attributes such as "ngIf" (see webpack.dev.js ):

        exclude: path.resolve(__dirname, 'src/index.html'),
        use: [
          {
            loader: 'html-loader',
            options: {
              minimize: true,
              caseSensitive: true,
            },
          },
        ],
      }

• Rename all your *.js files to *.ts

Replacing AngularJS wrappers

Many helper functions were present in the AngularJS, which are no longer available. Use following reference table to refactor.

AngularJS	Angular
angular.isArray(x)	Array.isArray(x)
angular.isObject(x)	HsUtilsService.isPOJO(x)
angular.isString(x)	typeof x === 'string'
angular.isDefined(x)	x !== undefined
angular.isUndefined(x)	x === undefined
angular.forEach(x, () => {})	either x.forEach(() => {}) if x is array, or Object.entries(x).forEach(() => {}) if x is object
angular.toJson(x)	JSON.stringify(x)
angular.merge(x, y)	HsUtilsService.structuredClone(x, y)
angular.extend(x, y)	x = {...x, ...y}
angular.element()	?

Rewrite all controllers to components

Use named exports instead of default ones.

Rewrite all services/providers to classes

Use named exports instead of default ones.

Upgrade hslayers-ng package

npm i hslayers-ng@^2.0.0

Rewrite module definitions

...

Rewrite components, services and templates

Rewrite ng template syntax

AngularJS	Angular
ng-class=	[ngClass]=
ng-click=	(click)=
ng-if=	*ngIf=
ng-mouseleave=	(mouseleave)=
ng-mouseover=	(mouseover)=
ng-repeat='value in array'	*ngFor='let value of array'
ng-show=	[hidden]= with negated condition
translate	i18n ?

etc. See https://angular.io/guide/ajs-quick-reference