Skip to content

Latest commit

 

History

History
189 lines (139 loc) · 13.5 KB

API.md

File metadata and controls

189 lines (139 loc) · 13.5 KB
Raw

Table of Contents

createMap

A utility function for creating a MapLibre Map object with an AmplifyMapLibreRequest object hooked into the map's requestTransformer

Create Map Parameters

  • options Object An object containing options for createMap. Extends MapLibre constructor options and select options are listed below. For a full list of constructor options check the MapLibre docs outlined here
    • options.mapConstructor MaplibreMap A map constructor which should be similar in shape to a MapLibre map. This argument allows you to specify at runtime whether the map should be constructed with MapLibre, MapBox, or any other forks of similar projects (optional, default: the peer dependency MapLibre version installed in your project)
    • options.region String AWS region (optional, default: selects the default region set in aws-exports or set in the Amplify.configure method)
    • options.container String MapLibre option for an HTML element in which MapLibre will render the map, or the element's string id
    • options.center Array<Coordinate> MapLibre option for the initial geographical centerpoint of the map. If it is not specified in the style, either, it will default to [0, 0] Note: Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
    • options.zoom Array<Coordinate> MapLibre option for the initial zoom level of the map. If zoom is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to 0 .

Returns Promise<MapLibreMap> Promise object containing a MapLibre map object

AmplifyMapLibreRequest

An object for encapsulating an Amplify Geo transform request and Amplify credentials

Parameters

  • currentCredentials ICredentials Amplify credentials used for signing transformRequests
  • region String AWS region

Returns AmplifyMapLibreRequest this

transformRequest

A callback function that can be passed to a maplibre map object that is run before the map makes a request for an external URL. This transform request is used to sign the request with AWS Sigv4 Auth. https://maplibre.org/maplibre-gl-js-docs/api/map/

Parameters

  • url string The function to use as a render function. This function accepts a single Carmen GeoJSON object as input and returns a string.
  • resourceType string The function to use as a render function. This function accepts a single Carmen GeoJSON object as input and returns a string.

Returns RequestParameters https://maplibre.org/maplibre-gl-js-docs/api/properties/#requestparameters

drawPoints

DrawPoints utility function for adding points to a map based on coordinate data or a FeatureCollection. Will add clustered points and styled markers by default with options for popups and other styles

Parameters

  • sourceName String A user defined name used for determining the maplibre data source and the maplibre layers

  • data (Array<Coordinate> | Array<Feature> | Array<NamedLocation>) An array of coordinate data, GeoJSON Features, or Named Locations used as the data source for maplibre

    • Coordinate data is an array of Latitude followed by Longitude
    • GeoJSON Features should be an array of Carmen GeoJSON Features
    • Named Locations is an array of objects containing the required field coordinates (same as the Coordinate data above) and the optional fields title and address. The title field will be bolded and on a separate line from the address field.

  • map maplibre-gl-js-Map A maplibre-gl-js map on which the points will be drawn

  • options Object An object containing options for changing the styles and features of the points rendered to the map, see the options for more details on available settings

    • options.showCluster boolean Determines whether or not points close together should be clustered into a single point (optional, default true)
    • options.clusterOptions String Object for determining cluster options (optional, default {})
      • options.clusterOptions.showCount boolean Default: false, determines whether to show the count for the number of points aggregated by a cluster
      • See ClusterOptions for more details
    • options.unclusteredOptions String Object for determining unclustered point options (optional, default {})
      • options.unclusteredOptions.markerImageElement HTMLImageElement optional, an image to use in place of the default marker. If only markerImageElement is passed then it will be used for both markerImageElement and activateMarkerImageElement. Images should be defined before the map load event is fired.
      • options.unclusteredOptions.activeMarkerImageElement HTMLImageElement optional, an image to use in place of the default active marker. If only markerImageElement is passed then it will be used for both markerImageElement and activateMarkerImageElement. Images should be defined before the map load event is fired.
      • options.unclusteredOptions.showMarkerPopup boolean Default: false, determines whether to show a popup on selection
      • options.unclusteredOptions.popupRender function Optional, overrides the default popup render function with function that accepts a Carmen GeoJSON feature and returns an HTML string
      • See UnclusteredOptions for more details
    • options.autoFit boolean Fits the map view around the points drawn if they are not currently in view (optional, default true)

  • mapStyle MAP_STYLE A required parameter that indicates the map style returned from Amazon Location Service. This is used to determine the default fonts to be used with maplibre-gl-js. View existing styles here

Returns DrawPointsOutput output An object containing the string id's of the sources and layers used to draw the points to the map. This includes the sourceId, clusterLayerId, clusterSymbolLayerId, unclusteredLayerId.

Properties

  • sourceId String The source used to contain all of the coordinate/feature data
  • clusterLayerId String The layer used for creating and styling the points that are clustered together
  • clusterSymbolLayerId String The layer used for creating styling the number that shows the count of points in a cluster
  • unclusteredLayerId String The layer used for creating and styling the individual points on the map and the popup when clicking on a point
  • show [function(): void] Utility function for setting the all layer's visibilty to "visible"
  • hide [function(): void] Utility function for setting the all layer's visibilty to "none"
  • setData [function(Array<Coordinate> | Array<Feature> | Array<NamedLocation>): void] Utility function for setting/updating draw data points

createAmplifyGeocoder

A utility method for constructing a MaplibreGeocoder with an AmplifyGeocoderAPI based on Amplify recommended settings.

Parameters

  • options Object An optional object containing MaplibreGeocoder optional parameters and some AmplifyGeocoder specific options (optional, default undefined)
    • options.autocomplete boolean Determines whether or not the geocoder will perform suggestion API calls while typing (optional, default true)
import { createAmplifyGeocoder } from "maplibre-gl-js-amplify";
import "@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css";
...
const geocoder = createAmplifyGeocoder();
map.addControl(geocoder);

AmplifyGeocoderAPI

An object wrapping Amplify Geo search APIs and returns forwardGeocode, reverseGeocode, and getSuggestions methods which are used by maplibre-gl-geocoder to perform search and suggestion queries

createDefaultIcon

A method that returns an Icon in the form of an HTMLImageElement that can be passed to the marker element in maplibre-gl-geocoder. Example:

import { AmplifyGeocoderAPI, createDefaultIcon } from "maplibre-gl-js-amplify";
import maplibregl from "maplibre-gl";
import MaplibreGeocoder from "@maplibre/maplibre-gl-geocoder";
import "@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css";
...
const geocoder = new MaplibreGeocoder(AmplifyGeocoderAPI, {
    maplibregl: maplibregl,
    showResultMarkers: { element: createDefaultIcon() },
});
map.addControl(geocoder);

drawGeofences

drawGeofences utility function for polygonal shapes geofences to a map based on geojson coordinate data or Geofences objects. Includes limited options for customizing the styles of the border and fill of the polygons.

Parameters

  • sourceName String A user defined name prefix used for determining the maplibre data source and the maplibre layers

  • data (Array<Polygon> | Array<Geofence> ) An array of polygon data or Geofence used as the data source for maplibre

    • Polygon data is an array of [LinearRing](Array of 4 or more coordinates, where the first and last coordinate are the same to form a closed boundary) where Linear Rings are an array of 4 or more coordinates, where the first and last coordinate are the same to form a closed boundary
    • Geofences are the object shape of values returned by Amplify Geo or Amazon Location Service

  • map maplibre-gl-js-Map A maplibre-gl-js map on which the points will be drawn

  • options Object An object containing options for changing the styles and features of the geofences rendered to the map, see the options below for more details on available settings

    • options.fillColor String Determines the color to use to fill in the interior of the polygon (optional, default black)
    • options.fillOpacity number Opacity value between 0 and 1.0 for the interior of the polygon (optional, default 0.3)
    • options.borderColor String Color of the border line around the polygon (optional, default black)
    • options.borderWidth number Pixel width of the border (optional, default 4)
    • options.borderOpacity number Opacity value between 0 and 1.0 for the interior of the polygon (optional, default 0.5)

Returns DrawGeofencesOutput output An object containing the string id's of the sources and layers used to draw the points to the map. This includes the sourceId, outlineLayerId, and fillLayerId. Also returns utility functions show() and hide() which toggle on or off the visibility of the geofences.

AmplifyGeofenceControl

A MapLibre control for managing geofences with Amplify CRUD APIs.

Parameters

  • options Object An object containing options for changing the geofence control
    • options.geofenceCollectionId String The id of an Amazon Location Service geofenceCollectionId to use for performing CRUD operations on (optional, defaults to whatever is the default collection in the aws-exports.js file)

Returns AmplifyGeofenceControl this

Example

const geofenceControl = new AmplifyGeofenceControl();
map.addControl(geofenceControl);