Getting started (for HSLayers NG 2.x)

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:

• http://ng.hslayers.org/examples/
• http://opentransportnet.eu/create-maps
• http://sdi4apps.eu/spoi/

Before You Start

This page describes how to create a HSLayers-NG based application with hslayers-ng 2.0 and newer. For a guide for older, but still supported version 1.x see Getting started (for HSLayers NG 1.x). If you are looking for an upgrade guide then check Upgrading from version 1.x.

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.

Create your first HSLayers-NG application

If you have not already done it before, install Node along with npm. Create new directory for your app, eg. 'first-app', navigate to it and run the following in terminal:

npm install hslayers-ng

Create empty html page and include the bundle script file in your html head

<script src="node_modules/hslayers-ng/dist/hslayers-ng.main.js"></script>

Configure the application

There are two basic ways how to configure you map application:

• hslayersNgConfig function
• custom config entry module.

hslayersNgConfig

A global hslayersNgConfig function, which returns a configuration object, NEEDS TO BE CREATED BEFORE loading the hslayers-ng.js script (insert it before the bundle script in the html head section). It returns a JSON object that describes the application's looks, behaviour and data it displays. See Configuration options for the list of available config options.

<script>
    function hslayersNgConfig(ol) {
      return {
        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>

That is it. Now you can finish creating the app by including the map DIV container in your html. Place it where the map should appear.

<hs ng-controller="Main" style="position: relative;"></hs>

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

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.

Custom config entry module

To have more customization options which require programming you can also write your own entry module which in this example is named app-js.ts, but can have any other file name. app-js.ts file is where you specify which HSLayers modules will be loaded for your specific application, which map layers will be displayed and other configuration parameters. You can also write some startup code here to load a map service, open some initial panels etc.

Some example html files are provided in https://github.com/hslayers/examples repository. The template app-js.ts uses png icons for layer groups which are included in https://github.com/hslayers/examples/tree/master/full directory.

HSLayers exposes OpenLayers as global 'ol' variable and 'angular', which are used in defining modules, layers and configuration.

Following example uses html:

 <script src="node_modules/hslayers-ng/dist/hslayers-ng.main.js"></script>
 <script src="app.js"></script>
 <hs ng-controller="Main" style="position: relative;"></hs>

And app-js.ts with explanations:

angular.module('hs', [
    'hs.sidebar',
    'hs.toolbar',
    'hs.layermanager',
    'hs.map',
    'hs.query',
    'hs.search', 'hs.print', 'hs.permalink', 'hs.measure',
    'hs.legend', 'hs.geolocation', 'hs.core',
    'hs.datasource_selector',
    'hs.save-map',
    'hs.ows',
    'gettext',
    'hs.compositions',
    'hs.info'
])
.directive('hs', (HsCore) => {
    'ngInject';
    return {
        template: HsCore.hslayersNgTemplate,
        link: function (scope, element) {
            HsCore.fullScreenMap(element);
        }
    };
})
.value('HsConfig', {
    open_lm_after_comp_loaded: true,
    layer_order: '-position',
    box_layers: [
        new Group({
            'img': 'osm.png',
            title: 'Base layer',
            layers: [
                new Tile({
                    source: new OSM(),
                    title: "OpenStreetMap",
                    base: true,
                    visible: true,
                    removable: false
                }),
                new Tile({
                    title: "OpenCycleMap",
                    visible: false,
                    base: true,
                    source: new OSM({
                        url: 'http://{a-c}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png'
                    })
                })
            ],
        })
    ],
    default_view: new View({
        center: fromLonLat([17.474129, 52.574000]),
        zoom: 4,
        units: "m"
    })
})
.controller('Main', function ($scope, HsCompositionParserService, HsConfig, HsLayoutService) {
    'ngInject';
    layoutService.sidebarRight = false;
});

For webpack bundling instructions see: Building-with-webpack

Proxy

For providing proxy functionality (to overcome CORS) you can use of of two methods. The CGI proxy is used by default, but you can switch to Node.js proxy by specifying the proxy prefix parameter in the application config (see below).

Node.js proxy

First option is to use Node.js proxy (based on cors-anywhere) that you can find in lib/proxy.js file. Simply run it as any other Node.js script in terminal by

node proxy.js

or deploy it as a service for production use. 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/'

CGI script

Another proxy option is a CGI script prepared in lib/hsproxy.cgi (or hsproxy_py3.cgi for Python 3). Copy it to your cgi-bin directory. It might be located in /usr/lib/ if you use Apache.

cp lib/hsproxy.cgi /usr/lib/cgi-bin/hsproxy.cgi

To enable cgi on Ubuntu, use

sudo a2enmod cgi
sudo service apache2 restart

If you are using nginx, see HsProxy configuration with uwsgi

Run the Application

If you dont plan to develop hslayers-ng, don't want to run tests and server files through npm managed http server, then you can skip all the following npm related steps.

We have preconfigured the project with a simple development web server, but you can always use a different web server.
The simplest way to start this server is:

npm start

Now browse to the app at http://localhost:8000/.

Running Unit Tests

See Testing.

Translating

Warning: This part of the page is outdated

Run

grunt nggettext_extract

from terminal to generate po file template in /po/template.po and for each example eg. examples/pilsen_traffic/template.pot . Rename it to *.po, translate, generate mo file and compile it. If you are using specific translations for your app or example merge the global po file into the specific one with msgcat before compiling. Compiling is done with

grunt nggettext_compile

It will generate components/translations/js/translations.js or examples/pilsen_traffic/translations.js files.

translations.js which contains the strings and also translating functionality is loaded by default like any other angular module from components/translations/js/translations.js in Core module. To have it use your own generated translations.js file override the path in hslayers.js file:

translations: hsl_path + 'examples/pilsen_traffic/translations' 

Updating AngularJS and Angular

You can update all dependencies by running:

npm update

Contact

raitisbe@gmail.com