Le mappe sono uno strumento molto potente, utile per georeferenziare attività e punti di interesse per gli utenti di una applicazione. Vengono utilizzate in moltissime situazioni e le possibilità di utilizzo vanno ben oltre la semplice visualizzazione aerea di un’area geografica.

Ad esempio, nei social network è possibile taggare i luoghi visitati come i ristoranti in cui si è cenato oppure i negozi dove si è acquistato un prodotto. In questo modo è possibile far conoscere ai propri followers o amici una posizione di interesse per suggerire, informare e incuriosire.

Un azienda che si occupa di logistica e trasporti utilizzerà applicazioni di localizzazione in tempo reale della posizione dei veicoli aziendali, attività necessaria sia per una rapida gestione degli automezzi che per garantire assistenza in caso di necessità.

Infine (ma la lista non finisce ovviamente qui), ci sono tutte quelle aziende che offrono servizi di field services (come quelle che operano nei settori delle utilities, della sanità, dell’edilizia, delle ristrutturazioni, della manutenzione di immobili e delle telecomunicazioni) che hanno bisogno di sistemi ed applicazioni che le supportino nella pianificazione degli interventi.

In questo articolo voglio spiegarti come creare una applicazione in Oracle APEX che utilizza dei dati geolocalizzati (ad esempio tramite le coordinate di latitudine e longitudine) e li mostra su una mappa.

Per fare questo esercizio utilizzerò la lista degli hotspot wifi free della città di Bologna, informazione recuperabile gratuitamente ed in tempo reale da questo link.

Prima di iniziare

Vorrei fare due precisazioni molto veloci.

La prima riguarda la versione di APEX da usare. Con l’avvento della release di 21.1 è possibile utilizzare il componente Maps per visualizzare delle coordinate spaziali.

In questo tutorial ti spiegherò come utilizzare questo componente standard. Se non hai ancora a disposizione un ambiente APEX con una versione uguale o superiore alla 21.1 puoi usare un ambiente gratuito di prova.

La seconda precisazione riguarda i dati che utilizzeremo per la dimostrazione.

Utilizzeremo una API REST messa a disposizione del comune di Bologna attraverso la piattaforma dati.gov.it, ossia il catalogo nazionale dei dati aperti delle pubbliche amministrazioni italiane.

Questa API, come tutte quelle messe a disposizione dalla pubblica amministrazione, possono essere utilizzate accedere gratuitamente e liberamente a questi dati di pubblico dominio.

Parte 1: crea una nuova APP

• Accedi all’App Builder e crea una nuova APP

• Aggiungi una pagina (Home) in questo momento di tipo Blank

• Configura nella Breadcrumb Bar una regione statica di tipo Hero dove mostrare il titolo dell’applicazione

• Seleziona nel Theme Roller il template da usare. Io, ad esempio, ho scelto il nuovo tema Redwood Light disponibile con la release 21.1 di APEX.

Parte 2: collega l’origine dati

Partiamo dai dati, ovvero dai punti che vogliamo rappresentare.

In generale, per rappresentare una qualunque posizione su una mappa abbiamo bisogno delle sue coordinate spaziali (ad esempio, latitudine e longitudine per intenderci). In realtà esisterebbe anche l’altitudine ma in questo momento non viene considerata.

Quindi, sempre parlando in generale, per visualizzare dei punti su una mappa abbiamo bisogno di avere nel sistema queste informazioni. I modi attraverso i quali queste informazioni vengono recuperate possono essere diversi.

Per fare questo esercizio utilizzeremo una sorgente dati esterna, ovvero collegheremo la nostra APP ad una API Rest ma, ovviamente, non è detto che si debba necessariamente fare sempre così.

Vediamo come fare.

• Dall’App Builder seleziona Shared Components

• Vai in Data Sources > REST Data Sources

• Clicca su Create

• Seleziona l’opzione From Scratch e clicca Next

• Dai un nome alla nuova Origine Dati
• Inserisci l’URL Endpoint del servizio dati: https://opendata.comune.bologna.it/api/v2/catalog/datasets/bolognawifi-elenco-hot-spot/exports/json

• Scegli l’opzione Authentication Required = No e clicca Discover

• Il tracciato dati che viene automaticamente mappato da Oracle APEX dovrebbe già essere corretto.

Sincronizza i dati con una tabella locale

Dovendo visualizzare delle informazioni che non sono soggette ad aggiornamenti frequenti può aver senso sincronizzare la sorgente dati REST con una tabella locale, definita direttamente nel database Oracle.

Questa scelta porta con sé due considerazioni: la prima è che riduciamo il traffico dati e, allo stesso tempo, ottimizziamo le prestazioni dell’applicazione che andrà a leggere i dati direttamente da una tabella locale piuttosto che interrogare un servizio web.

La seconda considerazione sta nel fatto che l’app funzionerà anche se il servizio REST dovesse essere per qualche motivo non raggiungibile.

Ovviamente questa non è detto sia la scelta adatta ad ogni situazione e la scelta migliore dipende dalle tue esigenze.

Per sincronizzare un servizio REST con una tabella locale esegui le seguenti operazioni.

• Dalla pagina di configurazione della sorgente REST clicca su Manage Synchronization

• Il sistema ti proporrà di creare una nuova tabella oppure di specificarne una già esistente.
• Specifica il nome della tabella in cui sincronizzare i dati e clicca Save

• Se la tabella non esiste ancora, APEX ci suggerirà di crearla. Possiamo eventualmente modificare lo script di creazione cliccando su Show SQL.
• Quando hai fatto clicca su Create Table.

• La tabella è pronta per essere sincronizzata

• Scegli una opzione di sincronizzazione. Io ho scelto l’opzione Replace.
• Clicca sul pulsante Schedule Builder per definire la schedulazione di aggiornamento.

• APEX permette diverse opzioni di schedulazione. Scegli l’opzione di sincronizzazione che preferisci e clicca su Set Execution Interval.

• Quando hai completato il setup di base, clicca Save and Run per interrogare il servizio web ed avviare il job di sincronizzazione automatica che sarà gestito direttamente da APEX in modo trasparente.

• Puoi vedere lo stato di esecuzione del job direttamente da questa sezione.

Parte 3: crea la mappa e configura il layer

Ora che abbiamo configurato l’Origine Dati possiamo finalmente configurare il componente Map.

Configurazione di base

• Accedi all’App Builder
• Seleziona o crea la pagina dove vuoi inserire il componente di tipo Map
• Aggiungi una nuova Region di nome WiFi Map

• Seleziona la WiFi Map e vai nelle proprietà della Region
• Seleziona il Type = Map

• Nella sezione Source imposta le seguenti opzioni:
  • Location: REST Source
  • Rest Source: il nome dell’origine dati che hai creato poco fa.
  • Use Synchronization table: Yes
• Per il momento lasciamo stare le altre opzioni di configurazione, sulle quali torneremo tra un attimo.

• Clicca sul tab Attributes della Region di tipo Map.
• Vai alla sezione Map e seleziona le seguenti opzioni:
  • Background: Default
  • Height: 640 pixels

• Nella sezione Controls scegli quali controlli interattivi devono essere disponibili sulla mappa.
  • Mousewheel Zoom: abilita lo zoom con la rotella del mouse
  • Rectangle Zoom: abilita lo zoom con la selezione del mouse
  • Scale Bar: visualizza la scala
  • Overview Map: visualizza una miniatura della mappa globale
  • Infinite Map: disattiva il bordo della mappa ad attiva lo scroll infinito
  • Get Browser Location: attiva la funzionalità di localizzazione automatica in base alla posizione del browser
  • Circle Tool: attiva la selezione di aree circolari
  • Distance Tool: attiva la funzione di calcolo delle distanze tra due punti

• Vai alla sezione Initial Positioning and Zoom e configura le seguenti opzioni
  • Get Position From Browser: Off
  • Type: Based on Spatial Result. Selezionando questa opzione la mappa verrà aperta impostando automaticamente il focus e lo zoom in funzione dei dati spaziali che devono essere rappresentati in quel momento.

• Ad esempio, quando avvio l’applicazione la mappa viene automaticamente impostata con il seguente livello di zoom che racchiude tutti i punti rappresentati.

• Vai alla sezione Attibutes e seleziona il sistema di riferimento (Sistema Metrico Decimale)

Configurazione dei layers

Uno degli funzionalità più interessanti del componente Map consiste nella possibilità di poter gestire più layer indipendenti che possono essere attivati o disattivati selettivamente.

Ad esempio, potresti creare un layer per mostrare gli hotspots wifi, un layer per mostrare i punti di interesse culturale (come musei e monumenti) ed un layer per mostrare le fermate di autobus e tram.

In questo esercizio ti mostrerò come configurare un singolo layer.

• Dalla visualizzazione della struttura seleziona il layer che APEX ha creato automaticamente

• Vai alle proprietà del layer e configura le seguenti opzioni.
• Identification: specifica le proprietà generali del layer
  • Name: WiFi Map
  • Layer Type: Points
  • Label: Wi-Fi

• Source: in questa sezione andrai a specificare quali dati mostrare nel layer
  • Location: Region Source. Selezionando questa opzione il layer verrà alimentato con gli stessi dati della regione principale. Tuttavia è possibile specificare una sorgente dati differente.

• Column Mapping: definisce il mapping tra le colonne della sorgente dati e il componente
  • Geometry Column Data Type: Longitude/Latitude. Avendo a disposizione latitudine e longitudine possiamo usare queste coordinate spaziali. Tuttavia APEX supporta altri due tipi di formato spaziale: GeoJSON e SDO_GEOMETRY.
  • Longitude Column: LON
  • Latitude Column: LAT
  • Primary Key Column: HOSTNAME

• Point Objects: definisce il tipo di icona da usare per evidenziare i punti sulla mappa
  • Icon CSS Classes: fa-map-marker-s
• Fill Color: definisce un colore di riempimento dell’icona
• Point Clustering: laddove la densità dei punti di visualizzare fosse troppo alta, è possibile raggrupparli sotto una sola icona (magari di tipo o dimensione diversa). Aumentando lo zoom (e riducendo quindi la densità) i vari punti vengono mostrati separatamente.
  • Icon CSS Classes: fa-map-marker-s fa-lg

• Qui sotto puoi vedere il risultato, dove il marker più grande racchiude 6 punti

• Tooltip: specifica il messaggio che deve essere visualizzato quando si posiziona il mouse sopra al marker.

• Info Window: specifica quali informazioni visualizzare quando l’utente clicca sul marker.

Parte 3: filtra i dati

Come molti tanti altri componenti di APEX è possibile filtrare in tempo reale i dati che vengono visualizzati anche con una Region di tipo Map.

Vediamo come creare una campo (un Page Item) che l’utente può usare per cercare un hotspot specifico.

• Crea un Page Item di tipo Text Field
  • Name: P1_SEARCH
  • Type: Text Field
  • Label: Cerca
  • Subtype: Search
  • Trim Spaces: Leading and Trailing
  • Text Case: No Change
  • Submit when Enter: Yes

• Crea una Dynamic Action collegata al Page Item P1_SEARCH

• Proprietà della Dynamic Action
  • Name: SearchHotspot
  • Event: Change
  • Selection Type: Item(s)
  • Item(s): P1_SEARCH

• Crea una Action di tipo Refresh che servirà per far scattare l’aggiornamento della mappa.
  • Action: Refresh
  • Selection Type: Region
  • Region: WiFi Map
  • Event: SearchHotspot

• Seleziona la Region Map ed imposta le seguenti proprietà
  • Source > Page Items to Submit: P1_SEARCH
  • Local Post Processing > Type: Where/Order By Clause
  • Local Post Processing > Where Clause: trim(upper(description)) like ‘%’ || trim(upper(:p1_search)) || ‘%’

Parte 4: visualizza l’elenco degli hotspot

Per rendere questa applicazione maggiormente fruibile ho creato un semplice Classic Report che viene automaticamente sincronizzato con i punti mostrati sulla mappa.

Il campo di ricerca che abbiamo creato filtrerà, quindi, non solo i punti visualizzati nella mappa ma anche i record mostrati nel report.

• Apri il Page Builder ed aggiungi una nuova Region di nome WiFi HotSpots
• Per comodità ho spostato il campo di ricerca P1_SEARCH dentro la region WiFi HotSpots

• Apri le proprietà del Classic Report ed imposta le seguenti opzioni:
  • Identification > Title: WiFi HotSpots
  • Identification > Type: Classic Report
  • Source > Location: Local Database
  • Source > Type: SQL Query
  • SQL Query: inserisci la query seguente
  • Page Items to Submit: P1_SEARCH

• Apri la scheda Attributes del Classic Report e seleziona il template Media List.

• Apri la definizione della Dynamic Action che abbiamo creato nella Parte 3 ed aggiungi la seguente Action, necessaria per aggiornare i Classic Report in funzione testo scritto nel filtro di ricerca

• Qui sotto puoi vedere i dettagli della Action di tipo Refresh

Conclusioni

In questo tutorial abbiamo imparato come creare una mappa in Oracle APEX integrata con una sorgente dati locale o remota.

Con l’avvento della release 21.1 l’implementazione di una mappa è diventato un lavoro davvero facile, grazie alla presenza di un componente dedicato che è completamente integrato all’interno del framework APEX e che quindi puoi personalizzare creando, ad esempio, Dynamic Actions personalizzate.

Ovviamente questa guida non è esaustiva perché ci sono tante altre opzioni che possono essere gestite nel componente Map. Spero comunque che ti sia utile per iniziare a sperimentare le sue potenzialità.

Fammi sapere cosa ne pensi!

Un abbraccio

Daniele