@mappingfactory/sdk-angular

This library provides a set of Angular services for working with the @mappingfactory/sdk-js. Those services are designed to be easy to use and provide a simple interface for common tasks such as searching for locations, getting directions, displaying and interacting with a map, and displaying a roadsheet.

Installation

You can install the library using your preferred package manager:

npm install @mappingfactory/sdk-angular

yarn add @mappingfactory/sdk-angular

Usage

To use the MappingFactory SDK in your Angular project, you first need to initialize the SDK using the MFCoreService. This service provides a method for initializing the SDK with your API key and other configuration options.

import { Component, OnInit, inject } from "@angular/core";
import { MFCoreService } from "@mappingfactory/sdk-angular";

@Component({
  // ...
})
export class AppComponent implements OnInit {
  mfCoreService: MFCoreService = inject(MFCoreService);

  constructor() {}

  ngOnInit(): void {
    // We initialize the SDK here
    this.mfCoreService.init({
      apiKey: "YOUR_API_KEY",
    });
  }
}

Once the SDK is initialized, you can use the other services provided by the SDK to perform various tasks related to mapping and location-based services. Here are some examples:

Direction Service

The MFDirectionService provides methods for calculating directions between two points.

import { MFDirectionService } from "@mappingfactory/sdk-angular";

@Injectable()
export class MyService {
  directionService: MFDirectionService = inject(MFDirectionService);

  constructor() {
    this.directionService.init({ geometries: "geojson" });
  }

  async exampleSearch(): Promise<void> {
    const direction = this.directionService.getInstance();

    direction.client.setCoordinates(
      { latitude: 48.8584, longitude: 2.2945 },
      { latitude: 43.2964, longitude: 5.37 }
    );
    const results = await direction.search();

    return results
  }
}

MapLibre Service

The MFMapLibreService provides a wrapper around the MapLibre GL library.

import { OnInit, Component, ElementRef, ViewChild } from "@angular/core";
import { MFMapLibreService } from "@mappingfactory/sdk-angular";

@Component({
  // ...
})
export class MyComponent implements OnInit {
  directionService: MFDirectionService = inject(MFDirectionService);
  mapLibreService: MFMapLibreService = inject(MFMapLibreService);

  @ViewChild("mapElement", { static: true }) mapElement!: ElementRef;

  constructor() {
    this.directionService.init({ geometries: "geojson" });
    this.mapLibreService.init();
  }

  ngOnInit(): void {
    const direction = this.directionService.getInstance();
    const wrapper = this.mapLibreService.getInstance();
    const maplibre = wrapper._client;

    const map = new maplibre.Map({
      container: this.mapElement.nativeElement,
      style: "https://demotiles.maplibre.org/style.json",
      center: [2.3522, 48.8566], // Paris
      zoom: 5,
    });

    // The `setMap` method saves a reference of the map and creates a new layer
    // for the route and start point.
    direction.setMap(map);
  }
}

Search Service

The MFSearchService provides methods that can create autocompletes and use geocoding services.

import { MFSearchService } from "@mappingfactory/sdk-angular";
import { OnInit, Component, ElementRef, ViewChild } from "@angular/core";

@Component({
  // ...
})
export class MyComponent implements OnInit {
  searchService: MFSearchService = inject(MFSearchService);

  @ViewChild("autocomplete", { static: true }) autocompleteElement!: ElementRef;

  ngOnInit(): void {
    this.searchService.init();

    const search = this.searchService.getInstance();

    const autocomplete = await search.autocomplete(
      this.autocompleteElement.nativeElement,
      {
        language: "fr",
      }
    );

    autocomplete._on("selected", (value) => {
      console.log(value);
    });
  }
}

Roadsheet Service

The MFRoadsheetService provides methods for generating a "roadsheet" or list of directions for a given route.

import {
  MFRoadsheetService,
  MFDirectionService,
} from "@mappingfactory/sdk-angular";
import { OnInit, Component, ElementRef, ViewChild } from "@angular/core";

@Component({
  // ...
})
export class MyComponent implements OnInit {
  directionService: MFDirectionService = inject(MFDirectionService);
  roadsheetService: MFRoadsheetService = inject(MFRoadsheetService);

  async ngOnInit(): Promise<void> {
    this.directionService.init({ geometries: "geojson" });
    this.roadsheetService.init();

    this.createRoadsheet();
  }

  async createRoadsheet(): Promise<void> {
    const direction = this.directionService.getInstance().client;
    const roadsheet = this.roadsheetService.getInstance().client;

    const departure = { latitude: 48.8584, longitude: 2.2945 }; // Paris
    const arrival = { latitude: 43.2964, longitude: 5.37 }; // Marseille

    direction.client.setCoordinates(departure, arrival);

    const results = await direction.search();
    const route = results.routes[0];
    const waypoints = route.waypoints;

    const html = await roadsheet.client.getHtml(route, waypoints);

    console.log(html);
  }
}

These are just a few examples of the services provided by this Angular SDK. For more information on how to use the SDK, please refer to the documentation of the @mappingfactory/sdk-js package.

Components

MichelinMap

The MichelinMap component is a part of @mappingfactory/sdk-angular that simplifies the process of adding and interacting with a MapLibre map in your Angular application. This component utilizes the MFMapLibreService service to manage map-related functionalities.

Features

Easy integration of MapLibre maps.
Customizable map options.
Callback function (onMapInit) for further map customization after initialization.

Props

options: A set of options to configure the MapLibre instance (excluding the container property, which is handled by the component). onMapInit: An optional callback that is invoked with the map instance after the map is initialized and styles are loaded. This can be useful for adding layers, sources or even with the MFDirectionService service to add a route to the map.

Example Usage

Use the MichelinMap component where needed.

<michelin-map
  [options]="mapOptions"
  (onMapInit)="onMapInit($event)"
></michelin-map>

mapOptions = {
  style: "https://demotiles.maplibre.org/style.json",
  center: [2.3522, 48.8566], // Paris
  zoom: 5,
};

public onMapInit(map: Map): void {
  console.log('Map is ready:', map);

  // In this example, 'click' is an event of type MapEventType
  // provided by the MapLibre-GL library.
  // You can customize event handlers according to your specific needs.
  map.on('click', () => {
    console.log('map click');
  });
}

MichelinAutocomplete

The MichelinAutocomplete component is a part of @mappingfactory/sdk-angular designed to provide an easy-to-use interface for implementing autocomplete functionality in your Angular applications. This component utilizes the MFSearchService service to manage autocomplete functionalities related to location and address search.

Features

Autocomplete functionality for searching locations and addresses.
Customizable options for search behavior and appearance.
Callbacks for various autocomplete events like selection, opening, closing, searching, and more.

Props

options: Custom options to configure the autocomplete behavior and appearance.
onSelect: Callback fired when an item is selected from the autocomplete suggestions.
onDropdownOpen: Callback fired when the dropdown opens.
onDropDownClose: Callback fired when the dropdown closes.
onSearch: Callback fired when a search is initiated.
onNoResults: Callback fired when no results are found.
onError: Callback fired when there is an error in searching.
onSuccess: Callback fired when a search is successful.
onClear: Callback fired when the autocomplete input is cleared.
onInit: Callback fired when the autocomplete manager is initialized.

Example Usage

Use the MichelinAutocomplete component where needed.

<michelin-autocomplete
  [id]="'autocompleteId'"
  (onSelect)="onSelectResult($event)"
></michelin-autocomplete>

public onSelectResult(value): void {
  // do something with the selected value
}

You can customize it by passing different options and handling various events according to your application's needs.

Development Environment Setup

To run this project locally, navigate to the Project Directory and follow these steps:

Install Dependencies:

Use npm to install the project's dependencies, you'll need to install the dependencies inside the root directory, demo folder and the projects/mapping-factory-sdk-angular using the following command:

npm install

Build the Project for Development:

Now that the dependencies are installed, you can build the SDK using the following command:

npm run build

Note This command needs to be run in the root directory of the project.

This command will output a dist folder in the root directory. This folder contains the compiled SDK files that are ready to be published to NPM.

Run the demo for Development:

You'll need to pack the dist folder using the following command:

npm run pack

This will create a .tgz file that can be installed using npm inside the demo folder using the following command:

npm install ../mappingfactory-sdk-angular-1.0.0.tgz

Now that the dependencies are installed, you can build the SDK using the following command:

npm run start

Note This command needs to be run in the root directory of the project or the demo folder.

Apply my changes from the SDK inside the demo:

If you want to see your changes inside the demo, you'll need to build and pack the dist folder using the following command:

npm run pack

This will create a .tgz file that can be installed using npm inside the demo folder using the following command:

npm install ../mappingfactory-sdk-angular-1.0.0.tgz