README.md

Mangol

Maps created with Angular & OpenLayers using Material design

About Mangol

Mangol is an open source web mapping library for combining Angular, Angular Material and OpenLayers to create a modern, responsive interactive GUI for web maps (M stands for Material, ang for Angular and ol for OpenLayers). The project is written in TypeScript and uses SCSS for styling. Mangol uses @ngrx/store under the hood for state management.

Live example

An online example can be opened here.

Run demo & edit source files

If you wish to see the built-in demos or modify the source files, simply run ng serve or npm run start to load the demo page on localhost:4200. With this command you can also watch file changes until you shut it down.

Use as npm dependency

You most likely want to use Mangol as an npm library in your Angular (TypeScript & SCSS) project. You can also do that since Mangol is on npm as well.

First, add Mangol as a dependency to your project:

npm install --save mangol

or

yarn add mangol

You have to add to your app.module.ts (or whatever you call it in your project, the one that gets bootstrapped in main.ts)

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { MangolModule } from 'mangol';

And in @NgModule add MangolModule and BrowserAnimationsModule to the imports:

imports: [
    ...,
    BrowserAnimationsModule,
    MangolModule,
    ...
]

Also add some vendor js files. If you use Webpack and created your project with @angular/cli, add the following libraries to your angular.json:

"scripts": [
    "node_modules/proj4/dist/proj4.js",
    "node_modules/jspdf/dist/jspdf.min.js"
]

At the beginning of your main SCSS file, you should import mangol.scss like this:

@import '~mangol/scss/mangol';

After that, you can use Mangol html tags in your templates such as

<mangol></mangol>

Run on localhost

At the moment when you run ng serve there will be the well-known error in the browser console: ExpressionChangedAfterItHasBeenCheckedError. Until this is fixed in Mangol please enable production mode in main.ts like this:

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';

enableProdMode();

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch(err => console.log(err));

Production build

Unfortunately there is a known issue with OL when build using Ahead-of-time (aot). To make aot possible, you should modify node_modules/ol/package.json file, and set "sideEffects": true. Another option is to disable optimization in your project config (in angular.json and set optimization: false, but I don't recommend it since the bundle size will be much bigger). After either of the above solutions, ng build --prod --aot should work fine.

Basic example

This is the simplest implementation of Mangol in a component (this will create a default map with one OpenStreetMap layer) :

import { Component } from '@angular/core';

@Component({
  selector: 'app',
  template: `
    <mangol></mangol>
  `
})
export class AppComponent {}

Configuring the component

You can further configure your Mangol component by creating a variable of type MangolConfig and add this property as an input for yor mangol component like this:

import { Component, OnInit } from '@angular/core';
import View from 'ol/View';
import { fromLonLat } from 'ol/proj.js';
import TileLayer from 'ol/layer/Tile';
import OSM from 'ol/source/OSM';
import { MangolConfig, MangolLayer } from 'mangol';

@Component({
  selector: 'app',
  template: `
     <mangol [config]="mangolConfig"></mangol>
  `
})
export class AppComponent implements OnInit {
  // Notice the MangolConfig type, this  is a helper interface to easily fill out the required and optional parameters for your Mangol configuration.
  mangolConfig = {} as MangolConfig;

  public ngOnInit() {
    this.mangolConfig = {
      map: {
        target: 'mangol-demo',
        view: new View({
          projection: 'EPSG:900913',
          center: fromLonLat(
            [19.3956393810065, 47.168464955013],
            'EPSG:900913'
          ),
          zoom: 4
        }),
        layers: [
          new MangolLayer({
            name: 'OpenStreetMap Layer',
            details: 'Here are the OSM layer details',
            layer: new TileLayer({
              source: new OSM(),
              visible: true
            })
          })
        ]
      },
      sidebar: {
        opened: true,
        toolbar: {
          layertree: {},
          measure: {}
        }
      }
    };
  }
}

Mangol is highly configurable through MangolConfig. Just check the API doc for further options (currently under heavy development).

Access and modify the internal State

After initialization you can also modify almost everything in your running Mangol app with a helper service called MangolService. Mangol is written in a reactive way which means almost every property is an RxJS Observable. Mangol itself uses @ngrx/store under the hood, and with the injectable MangolService you can access and modify the store state easily.

For example, if you wish to open the sidebar and change its title in runtime all you have to do is call the appropriate public functions form MangolService:

import { Component, OnInit } from '@angular/core';
import { MangolService, MangolConfig } from 'mangol';

@Component({
  selector: 'app-root',
  template: `
    <mangol [config]="mangolConfig"></mangol>
  `
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {

  config: MangolConfig;

  constructor(private mangolService: MangolService) {}

  ngOnInit() {
    // Initialize the MangolConfig with an empty and closed sidebar
    this.config = {
      sidebar: { title: 'Mangol Sidebar', collapsible: true, opened: true }
    };
    // After 1.5 seconds rename the sidebar title
    setTimeout(() => {
      this.mangolService.setSidebarTitle('My title modified after 1.5 sec');
    }, 1500);
    // After 3 seconds toggle the sidebar
    setTimeout(() => {
      this.mangolService.toggleSidebar();
      console.log('I just toggled the sidebar.');
    }, 3000);
  }
}

Styling

Mangol uses Material components and therefore it supports some SCSS customization. For example if you wish to alter the default colors, you can easily do that by overwriting the primary, accent and warn Material palettes before importing mangol.scss. Do it like this:

@import '~@angular/material/theming';
@include mat-core();
$mangol-primary: mat-palette($mat-teal);
$mangol-accent: mat-palette($mat-lime);
$mangol-warn: mat-palette($mat-deep-orange);
$mangol-theme: mat-light-theme($mangol-primary, $mangol-accent, $mangol-warn);

@import '~mangol/scss/mangol';

If you wish to set the component height, sidebar width or the quicksearch panel width, also do it before importing mangol.scss:

$mangol-height: 400px;
$mangol-sidebar-width: 450px;
$mangol-quicksearch-width: 250px;

@import '~mangol/scss/mangol';

Author

Mangol was created by Gergely Padányi-Gulyás