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

replace AngularJS wrappers
rewrite all controllers to components
rewrite all services/providers to classes
add TypeScript
upgrade hslayers-ng package
rewrite module definitions
rewrite components, services and templates

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.copy(x, y)`	`y = HsUtilsService.structuredClone(x)`
`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.

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

Upgrade hslayers-ng package

npm i hslayers-ng@^2.x

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
`data-target=`	`[attr.data-target]=` without curly braces
`$index`	`let item of items; let i = index` and use `i`
`translate`	`i18n` ?