Getting started - hslayers/hslayers-ng GitHub Wiki

HSLayers-NG mapping library

HSLayers-NG is a library which extends OpenLayers 6 functionality by providing a foundation to build map GUI and extra components such as layer manager, permalink generating, styling of vector features, including OpenGIS® Web Map Service Interface Standard (WMS) layers to the map in a user friendly way etc.

Check out the examples to get an idea:

Before You Start

HSLayers-NG is built on top of two major things: OpenLayers library and Angular framework. So in order to work with HSLayers-NG you should have some understanding of both. OpenLayers has a nice tutorial workshop to start with.

This page describes how to create a HSLayers-NG based application with hslayers-ng 3.0 and newer. For a guide for older, no-longer actively maintained, versions see Getting started (for HSLayers NG 1.x) and Getting started (for HSLayers NG 2.x). If you are looking for an upgrade guide then check Upgrading from version 1.x and Upgrading from version 2.x.

Create your first HSLayers-NG application

If you have not already done it before, install Node along with npm.

Installation

Create new directory for your app, e.g. 'first-app', navigate to it and run the following in terminal:

npm install hslayers-ng-app

Create empty html page and include <hslayers-app></hslayers-app> Where you want the map to appear.

Include hslayers-ng styles in page <head>:

<link rel="stylesheet" href="node_modules/hslayers-ng-app/styles.css">

Include hslayers-ng-app bundle scripts: (NOTE: the order of loading is mandatory)

<script src="node_modules/hslayers-ng-app/runtime.js"></script>
<script src="node_modules/hslayers-ng-app/polyfills.js"></script>
<script src="node_modules/hslayers-ng-app/vendor.js"></script><!-- Must be included since 4.x -->
<script src="node_modules/hslayers-ng-app/main.js"></script>

Configuration

A global hslayersNgConfig function needs to be created. It returns a JSON object which describes the application's looks, behaviour and data to display. See Configuration options for the list of available config options. HSLayers-NG exposes OpenLayers as global 'ol' variable, which is used in defining layers and configuration.

<script>
    function hslayersNgConfig(ol) {
      return {
        assetsPath: 'node_modules/hslayers-ng-app/assets/',
        default_layers: [
          new ol.layer.Tile({
            source: new ol.source.OSM(),
            title: "OpenStreetMap",
            base: true,
            visible: true,
            removable: false
          })
        ],

        default_view: new ol.View({
          center: ol.proj.fromLonLat([17.474129, 52.574000]),
          zoom: 4,
          units: "m"
        })
      }
    } 
  </script>

Now you can deploy your application through any web server. If you want to try locally you can use simple web server provided by the npm package http-server by running

npm i http-server npx http-server -a localhost -p 8000

Now browse to the app at http://localhost:8000/. You can see a live example of this application here.

Using Hslayers-NG components in existing Angular application

Some example html files are provided in https://github.com/hslayers/examples repository.

First you need to install hslayers library instead of hslayers-ng-app:

npm i hslayers-ng

Add peer dependencies: npm i bootstrap@^5.3 ol@^8.2 @angular/cdk@^17 @angular/common@^17 @angular/core@^17 @angular/forms@^17 @angular/compiler@^17 @angular/platform-browser@^17 @angular/platform-browser-dynamic@^17 @angular/localize@^17 @ngx-translate/core@^15 @ngx-translate/http-loader@^8 deepmerge@^4.0.0 dayjs@^1.0.0 @ng-bootstrap/ng-bootstrap@^16 ol-popup@^5.0.0 proj4@^2.8.1 share-api-polyfill@^1.0.0 rxjs@^7.0.0 zone.js@~0.14.0 xml-js@^1.6.11 ngx-cookie-service@^17 geostyler-style@^7.2.0 geostyler-sld-parser@^5 geostyler-openlayers-parser@^4 geostyler-legend@4 geostyler-qgis-parser@^2 ngx-color@^9 queue@^7 resumablejs@^1 d3@^7 jszip@^3 polygon-splitter@^0.0.11 polygon-clipping@^0.15.3 @popperjs/core@^2 ol-ext@^4

Once installed you need to import our main HslayersModule in your AppModule

import {HslayersModule} from 'hslayers-ng/core';
@NgModule({
  imports: [BrowserModule, HslayersModule],
  declarations: [AppComponent],
})
export class YourAppModule {}

Add hslayers to your component's html (app.component.html) with some optional styling used to position it in the page.

<style>
    hslayers {
      position: relative; 
      height: 100vh
    }
    @media only screen and (max-width: 600px) {
    hslayers {
      height: calc(100vh - 96px)
    }
  }
</style>
<hslayers></hslayers>

Import HsConfig service to set configuration options for hslayers map. It can be done also later using the update function.

export class AppComponent {
  constructor(private HsConfig: HsConfig) {
    this.HsConfig.update({
      assetsPath: 'assets/hslayers-ng',
      proxyPrefix: '/proxy/',
      default_layers: [
        new VectorLayer({
          title: 'Bookmarks',
          popUp: {
            attributes: ['name'],
          },
        })
      ]
    })
  }

The configuration options can also be set using attribute on <hslayers> element:

<hslayers [config]="config"></hslayers>

export class AppComponent {
  config = {
      assetsPath: 'assets/hslayers-ng',
      proxyPrefix: '/proxy/'
  }

Initiation of components.

Unlike hslayers-app, hslayers library (since v14) demands its users to manually initiate some of its functionality (panels, overlays) in order to improve final bundle size of container application. There are few options of how to handle this task.

First would be the one used internally in hslayers-app - createActivePanels and createGuiOverlay methods provided by thier constructorServices. This will result in creation of multiple chunks (chunk per component basically) which will be requested by browser only when necessary eg. hsConfig.panelsEnabled or hsConfig.componentsEnabled value for the respective component is set to true.

/**
* Dynamic panels
*/
import {HsPanelConstructorService} from 'hslayers-ng/shared/panel-constructor';
/**
* Dynamic overlays
*/
import {HsOverlayConstructorService} from 'hslayers-ng/shared/panel-constructor';

...


/**
* CREATE COMPONENTS BASED ON PANELS ENABLED CONFIG 
*/
this.hsPanelConstructorService.createActivePanels();

/**
 * SAME FOR GUI OVERALAY - based on componentsEnabled
 *  - toolbars
 *  - popup
 *  - mapGallery, geolocation etc.
 */
HsOverlayConstructorService.createGuiOverlay();

Other option is to enable each component individually - omitting services with dynamic imports (constructors) so that no lazy chunks are part of the build, only treeshaken parts included in main/vendor bundle

  • Create layermanager-gallery map overlay using create method provided by HsOverlayContainerServices
this.hsOverlayContainerServices.create(HsLayerManagerGalleryComponent, {});
  • Create layermanager component and its sidebar button
this.HsPanelContainerService.create(HsLayerManagerComponent, {});
this.hsSidebarService.addButton(
 this.hsSidebarService.buttonDefinition['layerManager'],
);

Proxy

For providing proxy functionality (to overcome CORS) you can use hslayers-server application.

It is a Node.js application based on cors-anywhere that you can install by:

npm i hslayers-server

Run with: npm start

To use this proxy in HSLayers-NG application, you have to set the proxyPrefix parameter in the config which specifies the proxy url, eg.

proxyPrefix: '/proxy/'

Contact

[email protected]

Quick Links: Home ➖ App configuration ➖ Layer configuration ➖ Cesium configuration ➖ Composition schema

⚠️ **GitHub.com Fallback** ⚠️