@limistah/react-here-map
React components for displaying and working with Here Map. It simplifies the use of the Here Map JavaScript API through incorporating them into React as components, which can be imported and easily rendered with easy configuration and modifications.
Installation
npm i --save @limistah/react-here-map
General Usage
;;; const points = lat: 525309825 lng: 133845921 lat: 525311923 lng: 133853495 lat: 525313532 lng: 133861756 lat: 525315142 lng: 133872163 lat: 525316215 lng: 133885574 lat: 525320399 lng: 133925807 lat: 525321472 lng: 133935785 ; ReactDOM;
Components
- HMap - Default export from this module, should be used as a parent for other components
- HMapPolyLine - Draws a polyline on the map
- HMapPolygon - Draws a polygon on the map
- HMapMarker - Puts a marker on the map
- HMapCircle - Draws a circle on the map
- HMapRectangle - Draws a rectangle on the map
- HMapGeoCode - Turns a physical address to a point on the map
- HMapRoute - Defines a route to locate two points
- HMapLayer - Adds additional informational layer on the map
Usage in details
HMap
Displays a Map for the types passed as props or default normal.map
Map types
normal: "map" "traffic" "panorama" "transit" "base" "xbase" "labels" satellite: "xbase" "base" "map" "traffic" "panorama" "labels" terrain: "xbase" "base" "map" "traffic" "panorama" "labels" incidents: true
All direct children of HMap
component receives:
- map A reference to the map object used to create the visual map. Docs
- platform A reference to H.service.platform Docs
- ui A reference to the ui object that does inclusion of ui elements. Docs
- __options A reference to the options merged with writable defaults used in bootsrapping the map and its items
In any case you wish to render a supported component of this library outside the context of the map, make sure to render in a place where the above props can be passed explicitly to avoid nasty, unfriendly errors.
In some cases as we will soon see, there is an option for passing a custom component with more enhancements (defined by the programmer), these props are received as first class directly from the containing parent and not from HMap, but still holds same object's reference
props
- version PropTypes.string - One of the supported version. Defaults to
'v3/3.0'
- appId PropTypes.string.isRequired - Application ID from account dashboard
- appCode PropTypes.string.isRequired - Application Code from account dashboard
- mapType PropTypes.string - One of the above types accessed as a dot prop. Default
'normal.map'
- interactive PropTypes.bool - Makes the map react to events. Needed for event handling
- includeUI PropTypes.bool - Determines
- mapEvents PropTypes.object - officially supported events
- mapOptions PropTypes.object - officially supported options
<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 />
HMapPolyLine
Draws a polyline on the map
Props
- points: PropTypes.array.isRequired - Array of objects containing lat and lng
- options: PropTypes.object - Officially supported options
- setViewBounds: PropTypes.bool - Makes the line centered in the container. Default
true
Usage
;const points = lat: 525309825 lng: 133845921 lat: 525311923 lng: 133853495 lat: 525313532 lng: 133861756 lat: 525315142 lng: 133872163 lat: 525316215 lng: 133885574 lat: 525320399 lng: 133925807 lat: 525321472 lng: 133935785 ; <HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 > <HMapPolyLine points=points /></HMap>;
HMapPolygon
Draws a polygon on the map
Props
- points: PropTypes.array.isRequired - Array containing points or an array of lat,lng string separated by comma.
- options: PropTypes.object - options for the polygon. Docs
Usage
;const points = 52 13 100 48 2 100 48 16 100 52 13 100;// const points = ['52,13']const polygonOptions = style: fillColor: "#FFFFCC" strokeColor: "#829" lineWidth: 8 ; <HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 > <HMapPolygon points=polygonPoints options=polygonOptions setViewBounds="true" /></HMap>;
HMapMarker
Puts a marker on the map
Props
- coords: PropTypes.object.isRequired Object with lat and lng for the marker
- icon: PropTypes.any.isRequired Icon for the marker
- options PropTypes.object Officially documented Options
- type: PropTypes.string One of
undefined
|DOM
. Defaultundefined
- setViewBounds: PropTypes.bool Centers the map with the marker. Default
true
Usage
;const coords = lat: 525309825 lng: 133845921 ;const icon = '<svg width="24" height="24" ' + 'xmlns="http://www.w3.org/2000/svg">' + '<rect stroke="white" fill="#1b468d" x="1" y="1" width="22" ' + 'height="22" /><text x="12" y="18" font-size="12pt" ' + 'font-family="Arial" font-weight="bold" text-anchor="middle" ' + 'fill="white">H</text></svg>';<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 > <HMapMarker coords=coords icon=icon /></HMap>;
HMapCircle
Puts a circle on the map
Props
- coords: PropTypes.object.isRequired - Object with lat and lng for the circle center point on the map
- options: PropTypes.object - Options for the circle. Docs
- radius: PropTypes.number - How large should one edge of the circle to the center point
- setViewBounds: PropTypes.bool - Centers the map with the circle. Default
true
Usage
; const coords = lat: 525309825 lng: 133845921 ; const circleOptions = style: strokeColor: "rgba(55, 85, 170, 0.6)" // Color of the perimeter lineWidth: 2 fillColor: "rgba(0, 128, 0, 0.7)" // Color of the circle ;<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 > <HMapCircle coords=cords radius=10000 options=circleOptions /></HMap>;
HMapRectangle
Puts a rectangle on the map
Props
- points: PropTypes.array.isRequired - Four element array of point defining the boundaries of the rectangle
- options: PropTypes.object - Options for the rectangle. Docs
- setViewBounds: PropTypes.bool - Centers the map with the circle. Default
true
Usage
; const points = 531 131 431 401;const rectangleOptions = style: fillColor: "#FFFFCC" strokeColor: "#E8FA75" lineWidth: 8 ;<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 interactive=true includeUI=true> <HMapRectangle points=points options=rectangleOptions /></HMap>;
HMapGeoCode
This uses React Hooks. Ensure that your react installation supports Hooks API
Props
- geoCodeParams: PropTypes.object - Depends on the type being used. Default params to be used when reverse and landmark are falsy, reverse params to be used when reverse is set to true, landmark params to be used when landmark is set to true
- children: PropTypes.element.isRequired - React Element that receives
map, platform, lat, lng
as props - reverse: PropTypes.bool - Should implement reverse geo coding
- landmark: PropTypes.bool - Should implement landmark geo coding
Usage
Address to positions
Converts an address to a position on the map
; const geoCodeParams = searchText: "200 S Mathilda Ave, Sunnyvale, CA";// Can render any map element, make sure to pass map and platform as props to the children to avoid unwarranted behaviorconst GeoMarker = <HMapMarker coords= lat lng map=map platform=platform key=key icon=icon />;// Child of HMapGeoCode receives same params as above.<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 interactive=true includeUI=true> <HMapGeoCode geoCodeParams=geoCodeParams> <GeoMarker /> </HMapGeoCode></HMap>;
Position to address(es)
Converts an position to address(es) on the map
;// Create the parameters for the reverse geocoding request:const reverseGeoCodingParameters = prox: "52.5309,13.3847,150" mode: "retrieveAddresses" maxresults: 1;// Can render any map element, make sure to pass map and platform as props to the children to avoid unwarranted behaviorconst ReverseGeoMarker = { ui; return null;}; // Child of HMapGeoCode receives same params as above.<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 interactive=true includeUI=true> <HMapGeoCode geoCodeParams=reverseGeoCodingParameters reverse=true> <ReverseGeoMarker /> </HMapGeoCode></HMap>;
Landmark Point
Locate landmark positions on the map
; const LandmarkGeoMarker = map platform ui lat lng location key _location ui; return null;;// Create the parameters for the landmark search request:const landmarkSearchParameters = searchText: "TXL"; // Child of HMapGeoCode receives same params as above.<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 interactive=true includeUI=true> <HMapGeoCode geoCodeParams=landmarkSearchParameters landmark=true> <ReverseGeoMarker /> </HMapGeoCode></HMap>;
HMapRoute
This uses React Hooks. Ensure that your react installation supports Hooks API
Displaying route on the Map Using normal line
Shows path to between two points based on params
Props
- routeParams: PropTypes.object - Officially documented route params
- lineOptions: PropTypes.object - Officially supported poly line options
- icon: PropTypes.any - Icon to be used for the marker
- markerOptions: PropTypes.object - Officially supported marker Options
- children: PropTypes.element - React element that receives
map, platform, ui, route, key, routeShape
as props - renderDefaultLine: PropTypes.bool - Should use default renderer instead of a custom renderer as children
- isoLine: PropTypes.bool - Use IsoLine instead of a Polyline
Usages
; // Create the parameters for the routing request:var routeParams = // The routing mode: mode: "fastest;car" // The start point of the route: waypoint0: "geo!50.1120423728813,8.68340740740811" // The end point of the route: waypoint1: "geo!52.5309916298853,13.3846220493377" // To retrieve the shape of the route we choose the route // representation mode 'display' representation: "display";const routeLineOptions = style: strokeColor: "blue" lineWidth: 10 arrows: fillColor: "white" frequency: 2 width: 08 length: 07 ;// Handles manipulation of the path between the two pointsconst RouteMarker = { // Retrieve the mapped positions of the requested waypoints: const startPoint = routewaypoint0mappedPosition; const endPoint = routewaypoint1mappedPosition; // Create a marker for the start point: const startMarker = lat: startPointlatitude lng: startPointlongitude ; // Create a marker for the end point: const endMarker = lat: endPointlatitude lng: endPointlongitude ; return <ReactFragment> <HMapPolyLine points=routeShape map=map setViewBounds=true /> <HMapMarker coords=startMarker map=map platform=platform icon=icon setViewBounds=false /> <HMapMarker coords=endMarker map=map platform=platform icon=icon setViewBounds=false /> </ReactFragment> ;}; // 1. Using a custom renderer <HMapRoute routeParams=routeParams icon=icon defaultDisplay=false lineOptions=routeLineOptions> <RouteMarker /></HMapRoute>; // Using default renderer, no children/child is required<HMapRoute routeParams=routeParams icon=icon defaultDisplay=true lineOptions=routeLineOptions/>;
Displaying route on the Map Using iso line
;// Create the parameters for the reverse geocoding request:const isoRoutingParams = mode: "fastest;car;" start: "geo!52.5,13.4" range: "900" rangetype: "time"; const RouteMarkerIso = map platform ui route routeShape center component return <ReactFragment> <Polygon points=routeShape options=polygonOptions setViewBounds=true map=map platform=platform /> <Marker coords=center map=map platform=platform icon=icon options=markerOptions setViewBounds=false /> </ReactFragment> ;; // Using default display<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 interactive=true includeUI=true> <HMapRoute routeParams=isoRoutingParams icon=icon isoLine=true defaultDisplay=true lineOptions=routeLineOptions /></HMap>; // Using a custom display<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 interactive=true includeUI=true> <HMapRoute routeParams=isoRoutingParams icon=icon defaultDisplay=false isoLine=true lineOptions=routeLineOptions > <RouteMarkerIso /> </HMapRoute></HMap>;
HMapLayer
Adds a layer to the map.
Individual layer holds different information
props
mapLayerType: PropTypes.string.isRequired In a dot prop form e.g mapLayerType="incidents", mapLayerType="normal.traffic"
normal: "xbase" "xbasenight" "base" "basenight" "map" "mapnight" "traffic" "trafficnight" "transit" "panorama" "panoramanight" "labels" "metaInfo" satellite: "xbase" "base" "map" "traffic" "panorama" "labels" terrain: "xbase" "base" "map" "traffic" "panorama" "labels" incidents: true
Usage
;<HMap style= height: "400px" width: "800px" appId=APP_ID appCode=APP_CODE mapOptions= center: lat: 525321472 lng: 133935785 > <HMapLayer mapLayerType="normal.trafficnight" /></HMap>;