Angular Azure Atlas

Angular 2+ wrapper for Microsoft's Azure Atlas Map

Pre-requisits

Key - An Azure Atlas key that can be obtained from your Azure Account portal.

Installation

Start by installing the repo using either NPM

npm install @acphh/angular-azure-atlas --save

or YARN

yarn add @apchh/angular-azure-atlas

Add the package to the app.module.ts file

Also make sure to import the map loader service into the providers under the app.module.ts file.

@NgModule({
    imports: [AngularAzureAtlasModule],
    providers: [MapLoaderService]
})

Add the MSDN Script/Style

Add the following two lines to the index.html file of your angular project between the tag.

<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/css/atlas.min.css?api-version=1" type="text/css" />
<script src="https://atlas.microsoft.com/sdk/js/atlas.min.js?api-version=1"></script>

Lazy Load the Map

In the component you will want to use the map in, lazy load the map using the MapLoaderService as follows:

key: string = '<Your Azure Atlas Key>'

constructor(public: mapService: LoadMapService) {}

ngOnInit(): void {
    this.mapService.load().toPromise().then(() => {
       atlas.setSubscriptionKey(this.key); 
    });
}

Adding the Map to your component HTML DOM:

You will need to add both a ViewChild as well as the following HTML to ensure the MapLoader can find the map div. In your Component.ts file add:

@ViewChild('atlas') AtlasMap: AtlasMapComponent;

In your component HTML add:

<azure-atlas-map [_id]="'<an-id>'" [_config]="config" #atlas *ngIf="mapService.isLoaded"></azure-atlas-map>

[_id] - The Id for this map on the DOMElements. This Id is nessesary for the module to find the map. [_config] - Initial Configuration for the map. You can find details of the config entries here.

Below is an example of a Map Config:

config = {
    zoom: 5,
    center: [27, 22],
    interactive: true,
    style: 'road'
};

Manipulating the Map after it is loaded:

When the map loads, an load event is emitted which you can monitor to manipulate the Map onces it has completley loaded.

<azure-atlas-map (loaded)="mapLoaded()"></azure-atlas-map>

In your component file, define the function that will be called and double check the Map is defined and loaded.

mapLoaded() {
    // Double check the map is loaded
    if(this.AtlasMap && this.mapService.isLoaded) {
        /// the map should be loaded at this point, so manipulate it as you would like.
    } else {
        // Otherwise, set a timeout and call the function again.
        setTimeout(() => this.mapLoaded(), 400);
    }
}

Preparing your data for the Map

The map has two classes that can be used to model your data: MapPoint - Used to define a Single Point on the map and its options. It consists of a Atlas Feature, which is simply an Atlas Point with all the data inside of it. A Tempalte Reference for a Popup Definition, and the layer name that this point belongs to.

export class MapPoint {
  point: atlas.data.Feature<atlas.data.Geometry, any>;
  popup?: TemplateRef<any>;
  layerName: string;
}

MapPointGroup - Used to group points that should go together in one layer, or simply group a bunch of points in order to prevent unesseasry number of layers on the map and reduce map load. Each MapPointGroup can have their own Pin/Text options applied.

export interface MapPointGroup {
  points: MapPoint[];
  layerOpts?: atlas.SymbolLayerOptions | atlas.BubbleLayerOptions;
  sourceOpts?: atlas.DataSourceOptions;
  groupName: string;
}

Creating a single MapPoint

You can define this model as such with your own custom data: Your data should at least have a latitude and longitude component

addPoint(data: any) {
    const point: MapPoint = {
        point: new atlas.data.Feature(
            new atlas.data.Point(
                new atlas.data.Position(parseFloat(data.lon), parseFloat(data.lat))
            )
        ),
        data, // the point data you want to save possibly to be used in a popup. 
        layerName:  'samplePoint'
    };
}

Grouping points

The Map point creator function takes a MapPointGroup and then processes them into pins and onto the map. If you have points that should go on different layers due to specific restrictions, you can generate multiple MapPointGroup's and assign them to their specific MapPointGroup, and then call the createPoints function and pass in the MapPointGroup.

Example: Points should be fieltered by their branch category:

let WGroup = new MapPointGroup({ points: [], groupName: 'washington'});
let TGroup = new MapPointGroup({ points: [], groupName: 'texas'});
data.forEach(point => {
    if(point.branch === "washington") {
        // Add to the Washington MapPointGroup
        WGroup.points.push( <instantiate a new MaPoint> )
    } else if (point.branch === "texas") {
        // Add to the Texas MapPointGroup
        TGroup.points.push( <instantiate a new MapPoint> )
    }
});

Then simply pass the MapPointGroup(s) to the map creatPoints() function and let it process them.

this.AtlasMap.createPoints(WGroup);
this.AtlasMap.createPoints(TGroup);

Todos

• Implement custom cluster icon definition.
• Implement a user layer legend to toggle layer views onto the map.
• Fix Map resize issue to fit full container rather than direct parent.

License

MIT