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 and services

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.

• 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() -> ?