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 (in fact, it uses both of these frameworks running side-by-side). 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 page provides a guide how to do it smoothly and painlessly.

Upgrade steps in recommended order

1. replace AngularJS wrappers
2. rewrite all controllers to components
3. rewrite all services/providers to classes
4. add TypeScript
5. upgrade hslayers-ng package
6. rewrite module definitions
7. 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'], under the resolve option
• • 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 ?

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

Rewrite app.js

Finally upgrade your app.js file (now app.ts). Name it app-js.ts and remove all imports of hslayers-ng modules from the top of the file.

Import AngularJS manually: import * as angular from 'angular';

Add a default export: export default angular.module('yourModuleDefinitionComesHere')

For the rest of the files see release notes 2.0.0.

Upgrading to 2.3.0 or higher

If you upgrade directly to ^[email protected] you need to align your webpack.config.js in a following way:

    extensions: ['.ts', '.js'],
    modules: [
      path.join(__dirname),
      path.join(__dirname, "./node_modules"),
      path.resolve(path.join(__dirname, "./node_modules", "hslayers-ng"))
    ].concat(hslPaths.paths)}

becomes

resolve: { symlinks: true,
    extensions: ['.ts', '.js'],
    modules: [
      path.join(__dirname),
      path.resolve(path.join(__dirname, "./node_modules")),
      path.resolve(path.join(__dirname, "./node_modules", "hslayers-ng")),
    ]}

and you can safely remove the import of hslPaths.

Upgrading to 2.5.0 or higher

If you upgrade directly to ^[email protected] you also need to enable SASS: npm i -D sass sass-loader

and edit your webpack.config.js to use it:

const fs = require('fs');

{
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              additionalData: fs.existsSync('./custom.scss')
                ? `@use "custom.scss" as *;`
                : '',
            },
          },
        ],
      },

From this version on, the scripts/bootstrap-isolate.js is no longer needed (see release notes 2.5.0).