Map List

Map List - documentazione operativa e tecnica

mapsgeomarkersstable

Overview

Map List

Visualizzazione geografica con marker, cluster, filtri su boundaries e template marker custom.

Screenshot reference (manuale utente)

  • manual__map__01.png: overview mappa route con toolbar, marker e clustering.
  • manual__map__02.png: configurazione avanzata archetype map (center/zoom/campi/info/template).

Use cases

  • Geo-localizzazione asset.
  • Tracking eventi geolocalizzati.
  • Heatmap o aggregazioni territoriali.

Differenza comportamento: point vs polygon

La mappa adatta automaticamente rendering e interazioni in base ai campi metadata con mc_ui_column_type.

  • Se e presente almeno una colonna point:

- ogni record viene renderizzato come marker (map-advanced-marker);

- supporta clustering (useClusterer);

- supporta drag marker (quando abilitato dalla toolbar);

- click su marker apre infoWindow con titleField/infoField e template.

  • Se e presente una colonna polygon:

- ogni record viene renderizzato come poligono (map-polygon);

- non usa marker clusterer;

- il filtro boundaries puo usare anche la geometria poligonale;

- click su poligono apre la stessa infoWindow dei marker (posizionata sul punto cliccato o, in fallback, sul centro geometrico).

  • Se sono presenti entrambi (point e polygon):

- il componente puo mostrare entrambi i layer;

- la toolbar privilegia le azioni coerenti col tipo principale (drag marker su scenari marker, edit polygons su scenari polygon-only);

- il filtro maparea usa il primo campo geografico disponibile tra point/polygon.

Note operative

Assicurarsi che i campi coordinate siano correttamente mappati nei metadata colonna.

md_props_bag: archetypes.map

Snippet 1JSON
{
  "archetypes": {
    "map": {
      "advancedFilter": false,
      "center": {
        "lat": 39.8283,
        "lng": -98.5795
  • advancedFilter: quando true mostra la wuic-filter-bar per l'archetype map (a livello data-repeater).
  • zoom: zoom iniziale.
  • center.lat/center.lng: centro iniziale mappa; se mancanti viene usato il comportamento default del componente.
  • minZoom/maxZoom: limiti zoom.
  • useCurrentLocation: usa geolocalizzazione browser come centro.
  • useClusterer: abilita clustering marker.
  • filterByBoundaries: filtra i record visibili in base al bounding box corrente.
  • titleField: campo metadata usato come titolo marker.
  • infoField: campo metadata usato come info base marker.
  • customMarkerImageSrc: URL marker fisso (immagine o SVG inline applicata a tutti i marker).
  • customMarkerImageSrcField: nome del campo record che contiene URL immagine o SVG inline (<svg ...>...</svg>); auto-detect del formato. Vince su markerColorField e markerContentCallback.
  • markerColorField: nome del campo record che contiene un colore CSS (#rrggbb); il marker viene reso come PinElement colorato. Ignorato quando customMarkerImageSrcField e' valorizzato per quel record (immagine ha precedenza).
  • markerContentCallback: callback JS per contenuto marker.
  • infoFunction: callback JS per render info window. (Alternativo a itemTemplateString)
  • itemTemplateString: template custom del contenuto. (Alternativo a infoFunction)
  • polyline: overlay polyline per tracking percorsi GPS — vedi sezione dedicata sotto.

Personalizzazione marker per-record (colore + immagine/SVG)

L'archetype map permette di **personalizzare ogni marker in base ai dati del

singolo record** senza scrivere callback JS, configurando i campi del record

direttamente dal mdpropsbag.

Priorità di rendering del marker

Il framework risolve il contenuto del marker in quest'ordine (prima che matcha vince):

1. `customMarkerImageSrcField` — campo record con URL immagine o SVG inline.

Auto-detect: se la stringa inizia con <svg, viene wrappata in <div> come

AdvancedMarker content; altrimenti viene messa in <img src>.

2. `customMarkerImageSrc` — immagine/SVG fisso applicato a tutti.

3. `markerColorField` — colore CSS per-record, reso come PinElement

(pin Google Maps standard colorato).

4. `markerContentCallback` — callback JS user-supplied (riceve record).

Esempio: campo colore_marker + svg_marker su tabella mezzi

Schema DB Dati (estratto):

Snippet 2SQL
ALTER TABLE dbo.mezzi ADD colore_marker NVARCHAR(7) NULL;       -- es. '#dc2626'
ALTER TABLE dbo.mezzi ADD svg_marker    NVARCHAR(MAX) NULL;     -- SVG inline o URL

Metadata colonna:

Colonnamc_ui_column_typevoa_classNote
colore_markercolor1color picker nativo (#rrggbb)
svg_markertxt_area1SVG inline o URL — opzionale, sovrascrive il colore

Propsbag dell'archetype map sulla route che renderizza i mezzi:

Snippet 3JSON
{
  "archetypes": {
    "map": {
      "markerColorField": "colore_marker",
      "customMarkerImageSrcField": "svg_marker"
    }
  }

Comportamento runtime:

  • record con svg_marker = '<svg ...>...</svg>' → marker = SVG inline (override del colore).
  • record con svg_marker = 'https://.../truck.png' → marker = <img> con quella URL.
  • record con svg_marker vuoto e colore_marker = '#16a34a' → marker = PinElement verde.
  • record con entrambi vuoti → marker default Google Maps.

Polyline overlay (tracking percorsi GPS)

L'archetype map puo' renderizzare una polyline per gruppo di record

(es. tracciato GPS storicizzato di un mezzo per una giornata) leggendo le

coordinate dalla colonna point esistente sulla route, raggruppando i record

per un campo (groupByField) e ordinandoli per un campo temporale

(orderByField).

Quando polyline.enabled=true la mappa NON renderizza un marker per ogni

record: solo un marker per gruppo, posizionato sull'**ultimo punto

temporale** (il piu' recente). Tutti gli altri record sono rappresentati come

nodi della polyline.

Configurazione minima

Snippet 4JSON
{
  "archetypes": {
    "map": {
      "advancedFilter": true,
      "polyline": {
        "enabled": true,
        "groupByField": "mezzo_id",

Tutte le opzioni polyline

  • enabled: abilita l'overlay polyline (default false).
  • groupByField: campo record per raggruppare i record in polyline distinte

(es. mezzo_id, tracking_session_id). Se omesso, tutti i record finiscono

in un'unica polyline globale.

  • orderByField: campo record per ordinare i punti dentro ogni gruppo

(es. timestamp_pos). Se omesso, viene usato l'ordine di arrivo.

  • pointField: campo record da cui leggere {lat,lng}. Default:

auto-detect della prima colonna con mc_ui_column_type='point' nel

metaInfo (la stessa che il map-list usa per i marker normali).

  • colorField: campo record con colore polyline per-gruppo (CSS #rrggbb).

Il colore viene letto dal primo record del gruppo (assume omogeneita').

Sovrascrive strokeColorByGroup e strokeColor. Tipico use-case: portare

in view il colore_marker configurato sull'entita' lookup (es. mezzi).

  • strokeColor: colore polyline fisso (default #1d4ed8). Usato solo se

colorField non risolve e strokeColorByGroup=false.

  • strokeColorByGroup: se true e colorField non e' settato, ogni gruppo

riceve un colore distinto da una palette interna (8 colori).

  • strokeWeight: spessore tratto in px (default 4).
  • strokeOpacity: opacita 0..1 (default 0.85).
  • snapToRoads: se true, la polyline viene snappata alle strade reali via

Google Maps Routes API (Route.computeRoutes, fallback automatico al

legacy DirectionsService se la libreria routes non e' caricata).

Richiede "Routes API" abilitata sulla key in Google Cloud Console.

La chiamata viene chunkata a 25 waypoint per request (limite Routes API).

  • showMarkers: se false, nasconde anche il marker last-in-group (default

true — un marker per gruppo).

  • showWaypointDots: se true, disegna un <map-circle> (cerchio

geografico) su ogni waypoint originale del record. Utile per distinguere

visivamente i punti GPS storicizzati nel DB dal path

interpolato/snappato.

  • waypointDotRadius: raggio in metri del dot (default 8).
  • travelMode: modalita di viaggio per snapToRoads (DRIVING/WALKING/

BICYCLING). Per giri cittadini con waypoint in ZTL/zone pedonali,

preferire WALKING (DRIVING da spesso no results in centro storico

italiano).

Combinare colore polyline + colore marker dalla stessa colonna

Se la tabella entita' (es. mezzi) ha gia' un campo colore_marker,

configura lo stesso campo sia per il marker che per la polyline portando

quel campo nella view sorgente:

Snippet 5SQL
CREATE VIEW vw_mezzi_posizioni_giorno AS
SELECT p.*, m.colore_marker, m.svg_marker, ...
FROM dbo.mezzi_posizioni p JOIN dbo.mezzi m ON m.id = p.mezzo_id;
Snippet 6JSON
{
  "archetypes": {
    "map": {
      "markerColorField": "colore_marker",
      "customMarkerImageSrcField": "svg_marker",
      "polyline": {
        "enabled": true,

Ogni mezzo avra' marker, polyline e dot dello stesso colore configurato sul

record mezzi (l'utente lo modifica dall'anagrafica e si propaga ovunque).

Per il mezzo con svg_marker valorizzato, il marker sara' l'icona custom

(SVG inline o immagine URL) e il colore continuera' ad essere usato per

polyline + dot.

Contesto Template (itemTemplateString)

Nel template custom sono disponibili questi input:

  • record: record corrente (in map archetype coincide con rowData.record quando presente).
  • rowData: payload evento marker/poligono corrente.
  • metaInfo: metadati tabella/colonne della datasource.
  • datasource: riferimento al componente datasource associato.

Contesto runtime usato dal framework:

Snippet 7ts
inputs: { record: item, rowData: item, metaInfo: metaInfo, datasource: datasource }

Eventi e subscriptions (host)

Eventi disponibili su wuic-map-list:

  • onMapClick: click su mappa (google-map mapClick).
  • onMarkerClick: click su marker.
  • onMarkerDragStart: inizio drag marker.
  • onMarkerDragEnd: fine drag marker (con posizione finale).
  • onPolygonClick: click su poligono.
  • onPolygonShapeChangedEvent: shape changed su poligono in edit mode.
  • onMapDataBound: emesso quando il wrapper completa il binding dati dal datasource.

Esempio template:

Snippet 8HTML
<wuic-map-list
  [hardcodedDatasource]="citiesDs"
  (onMapClick)="handleMapClick($event)"
  (onMarkerClick)="handleMarkerClick($event)"
  (onMarkerDragStart)="handleMarkerDragStart($event)"
  (onMarkerDragEnd)="handleMarkerDragEnd($event)"
  (onPolygonClick)="handlePolygonClick($event)"

Esempio subscribe (ViewChild):

Snippet 9ts
@ViewChild(MapListComponent) mapList?: MapListComponent;
private readonly subs = new Subscription();

ngAfterViewInit(): void {
  if (!this.mapList) return;
  this.subs.add(this.mapList.onMapClick.subscribe((e) => console.log(e)));
  this.subs.add(this.mapList.onMarkerClick.subscribe((e) => console.log(e)));

<!-- import-and-mount -->

Import e mount (componente Angular)

Importa MapListComponent da 'wuic-framework-lib' e montalo col DataSource del framework:

Snippet 10ts
import { DataSourceComponent, MapListComponent } from 'wuic-framework-lib';

@Component({
  selector: 'app-esempio',
  imports: [DataSourceComponent, MapListComponent],
  template: `
    <wuic-data-source #ds [hardcodedRoute]="'<route>'" [autoload]="true"></wuic-data-source>

Nomi ESATTI (barrel wuic-framework-lib): classe MapListComponent, selector <wuic-map-list>. Importa quella classe, non altri nomi inventati (es. un prefisso Lazy dove non c'è, o viceversa) → altrimenti il build dà has no exported member.

Config metadata-driven: il tag accetta SOLO gli input standard [hardcodedRoute], [hardcodedDatasource], [autoload], [hideToolbar]. La configurazione specifica (qui: il campo location/coordinate) NON è un input HTML ([groupField], [type], ecc. danno NG8002 not a known property) → va nei metadata (md_props_bag/archetipo) o in-code via metaInfo.

Screenshot

map-list / manual-map-01
map-list / manual-map-01
map-list / manual-map-02
map-list / manual-map-02
map-list / map-list-main
map-list / map-list-main
Map list - marker
Map list - marker
Map list - poligoni
Map list - poligoni