Quick Start

Get your first interactive, declarative map up and running in your Angular application in just a few steps.

1. Installation

Install the library along with its peer dependency, OpenLayers:

npm install aur-openlayers ol
npm install --save-dev @types/ol

2. Basic Component Setup

To use the framework, import MapHostComponent into your standalone component and define a basic MapHostConfig.

In this example, we will create a simple map that displays a list of points.

import { Component } from '@angular/core';
import { 
  MapHostComponent, 
  MapHostConfig, 
  MapContext, 
  VectorLayerDescriptor 
} from 'aur-openlayers';
import { fromLonLat } from 'ol/proj';
import { Point } from 'ol/geom';
import Style from 'ol/style/Style';
import CircleStyle from 'ol/style/Circle';
import Fill from 'ol/style/Fill';

// 1. Define your business model
interface Station {
  id: string;
  name: string;
  lat: number;
  lng: number;
}

@Component({
  selector: 'app-simple-map',
  standalone: true,
  imports: [MapHostComponent],
  template: `
    <mff-map-host 
      [config]="mapConfig" 
      (ready)="onMapReady($event)">
    </mff-map-host>
  `,
  styles: [`:host { display: block; height: 500px; }`]
})
export class SimpleMapComponent {
  // 2. Describe the map behavior and layers
  readonly mapConfig: MapHostConfig = {
    schema: {
      layers: [
        {
          id: 'stations-layer',
          feature: {
            id: (model: Station) => model.id,
            geometry: {
              // Convert model to OpenLayers geometry
              fromModel: (model: Station) => new Point(fromLonLat([model.lng, model.lat])),
              // Sync changes back to model (e.g., after dragging)
              applyGeometryToModel: (prev: Station) => prev, 
            },
            style: {
              base: () => ({ color: '#3b82f6', radius: 8 }),
              render: (opts) => new Style({
                image: new CircleStyle({
                  radius: opts.radius,
                  fill: new Fill({ color: opts.color })
                })
              })
            }
          }
        }
      ]
    },
    view: {
      centerLonLat: [37.61, 55.75], // Moscow
      zoom: 10
    },
    osm: true // Enable OpenStreetMap background
  };

  onMapReady(ctx: MapContext) {
    // 3. Populate the layer with data
    const stations: Station[] = [
      { id: '1', name: 'Central', lat: 55.75, lng: 37.61 },
      { id: '2', name: 'North', lat: 55.80, lng: 37.60 }
    ];

    const layerApi = ctx.layers['stations-layer'];
    layerApi.setModels(stations);
  }
}

3. Adding Interactions (Optional)

One of the main strengths of aur-openlayers is handling interactions like dragging (translating) or selecting features declaratively.

To make the points draggable, simply add the interactions block to your layer descriptor:

// Inside your VectorLayerDescriptor
interactions: {
  translate: {
    cursor: 'pointer',
    state: 'DRAGGING', // Applies this style state while moving
    onEnd: (item) => {
      console.log('New position:', item.model.lat, item.model.lng);
      return true;
    }
  }
}

4. Key Concepts to Remember

MapSchema: The blueprint of your map. It defines what layers exist and how they look.
VectorLayerDescriptor: The contract for a specific layer. It maps your data (model) to a Feature on the map.
MapContext: Provided via the (ready) event. Use it to access VectorLayerApi for adding, removing, or updating your data models.
Single Source of Truth: You manage your array of models; the framework handles the creation, destruction, and synchronization of OpenLayers Feature objects automatically.

Next Steps

Custom Popups: Use the popup-host feature to show Angular components over map features.
Complex Styling: Use states (like HOVER or SELECTED) to change appearance dynamically.
Clustering: Enable clustering by adding cluster: true to your layer descriptor.