Map Component

Introduction

The Map Component renders an inline Google Maps view for CXTMS app modules. It plots markers from either an explicit markers array or a dispatch route/template stops array, ignores invalid or ungeocoded coordinates, and can fire actions when a marker is clicked.

The component loads Google Maps with the organization-specific API key from configuration. If the key is unavailable, the component shows an unavailable state instead of rendering a blank map.

YAML Structure

component: map
name: routeMap
props:
  type: google
  height: 520
  center:
    lat: 41.8781
    lng: -87.6298
  zoom: 10
  fitBounds: true
  showUnmappedNote: true
  showInfoWindow: true
  stops: "{{ route.stops }}"
  markers:
    - id: stop-1
      label: "1. Warehouse"
      lat: 41.8781
      lng: -87.6298
      address: "Chicago, IL"
  onMarkerClick:
    - setStore:
        selectedStop: "{{ result }}"

Props

Prop	Type	Default	Description
type	string	google	Map provider. Only google is currently supported.
height	number	520	Map viewport height in pixels.
center	object	auto	Optional { lat, lng } center. Values may be numbers or numeric strings.
zoom	number	4 or auto	Initial zoom. A single marker defaults to zoom 14; fitted multi-marker maps clamp at zoom 15.
markers	array	-	Explicit marker list. Takes precedence over stops.
stops	array	-	Dispatch route/template stops. Converted to markers using each stop contact's shipping address.
fitBounds	boolean	true	Auto-fit the viewport to all valid markers when no explicit center is provided.
showUnmappedNote	boolean	true	Show a caption listing markers/stops that could not be plotted.
showInfoWindow	boolean	true	Show a Google Maps info window when a marker is clicked.
onMarkerClick	action[]	-	Actions fired after a marker click. Receives the clicked marker as result.

Marker Shape

id: stop-1
number: 1
label: "1. Warehouse"
lat: 41.8781
lng: -87.6298
address: "Chicago, IL"
stopType: Pickup

lat and lng can be numbers or numeric strings. Coordinates outside valid latitude/longitude ranges are treated as unmapped. Coordinates at 0,0 are also treated as unmapped because route stops use that as a create-time default before geocoding.

Stop Mapping

When markers is not supplied, stops are converted into markers from:

• dispatchRouteStopId or dispatchRouteTemplateStopId as id
• stop position as number
• stopContact.name as the marker label
• stopContact.shipping.latitude / longitude as coordinates
• stopContact.shipping.addressLine as the info-window address
• stopType for display in the info window

Deleted stops (isDeleted: true) are skipped.

Examples

Route stops map

component: map
name: dispatchRouteMap
props:
  height: 560
  stops: "{{ dispatchRoute.stops }}"
  fitBounds: true
  onMarkerClick:
    - setStore:
        selectedStopId: "{{ result.id }}"

Explicit markers

component: map
name: terminalMap
props:
  height: 420
  center:
    lat: 33.749
    lng: -84.388
  zoom: 8
  markers:
    - id: atl
      label: Atlanta Terminal
      lat: 33.749
      lng: -84.388
      address: "Atlanta, GA"
    - id: sav
      label: Savannah Terminal
      lat: 32.0809
      lng: -81.0912
      address: "Savannah, GA"
  showUnmappedNote: false

Best Practices

• Use markers when the module already has normalized location objects.
• Use stops for dispatch route and route template screens so marker numbering matches stop order.
• Keep fitBounds: true unless the module needs a fixed map region.
• Handle onMarkerClick for drill-in workflows, side-panel selection, or syncing a selected stop with the rest of the screen.
• Make sure the organization has apps.google.googleMapsApiKey configured before relying on the component in production.