Leaflet dla TYPO3

Mapy OpenStreetMap przez Leaflet zastępują Google Maps bez kosztów licencji i ryzyka RODO

Google Maps od 28 000 wyświetleń mapy miesięcznie kosztuje pieniądze i przesyła dane użytkowników na serwery w USA. Dla firm ze wyszukiwarką oddziałów, Store Locatorem lub mapą lokalizacji na stronie to dwa problemy naraz: budżet i ochrona danych. Leaflet rozwiązuje oba. Otwartoźródłowa biblioteka JavaScript renderuje interaktywne mapy oparte na danych OpenStreetMap, działa w całości po stronie klienta i nie ma kosztów licencji. Rozszerzenie TYPO3 integruje Leaflet jako element treści: redaktorzy zarządzają lokalizacjami w backendzie, rozszerzenie generuje mapę we frontendzie.

Dla firm z 5 do 500 lokalizacjami Leaflet jest standardową rekomendacją. Dopiero gdy potrzebne są funkcje specyficzne dla Google, takie jak Street View, budynki 3D lub dane o ruchu drogowym na żywo, Google Maps jest lepszym wyborem. We wszystkich pozostałych przypadkach Leaflet dostarcza tę samą funkcjonalność przy zerowych kosztach licencji i bez dyskusji o ochronie danych.

Typowe scenariusze to wyszukiwarki oddziałów, mapy nieruchomości i lokalizacje wydarzeń

Najczęstszym scenariuszem jest wyszukiwarka oddziałów lub lokalizacji. Firma z 20 do 200 oddziałami pokazuje wszystkie lokalizacje na interaktywnej mapie. Użytkownicy mogą przybliżać, szukać po kodzie pocztowym i klikać markery, aby zobaczyć adres, godziny otwarcia i dane kontaktowe. Przy gęstym rozmieszczeniu markerów clustering grupuje pobliskie lokalizacje w marker zbiorczy, który przy przybliżaniu rozkłada się na pojedyncze markery. Typowa wyszukiwarka oddziałów ze 100 lokalizacjami i clusteringiem ładuje się w czasie poniżej 500 ms.

Drugi scenariusz: mapy nieruchomości i obiektów. Pośrednicy, zarządcy nieruchomości i spółki mieszkaniowe pokazują dostępne obiekty na mapie. Markery zawierają podstawowe informacje (cena, liczba pokoi, powierzchnia) jako popup i linkują do strony szczegółów. Rozszerzenie TYPO3 może renderować rekordy obiektów z tabeli Extbase jako markery.

Trzeci scenariusz: lokalizacje wydarzeń i turystyka. Organizatorzy, organizacje turystyczne i miasta pokazują POI (Points of Interest), trasy i miejsca wydarzeń na mapie. Leaflet obsługuje oprócz markerów punktowych także linie (dla szlaków turystycznych) i wielokąty (dla obszarów), co czyni go elastycznym narzędziem dla zastosowań turystycznych.

Architektura techniczna czysto oddziela backend danych od renderowania mapy

Rozszerzenie TYPO3 przechowuje dane lokalizacji jako rekordy Extbase w dedykowanej tabeli. Każdy rekord zawiera nazwę, adres, współrzędne (szerokość/długość geograficzna), opis i opcjonalne pola takie jak godziny otwarcia, numer telefonu i zdjęcie. Współrzędne można wprowadzać ręcznie lub automatycznie określać z adresu przez usługę geocodingu.

We frontendzie rozszerzenie renderuje kontener mapy i inicjalizuje Leaflet przez JavaScript. Kafelki mapy są ładowane z konfigurowalnego serwera kafelków. Standardem jest OpenStreetMap, ale także Mapbox, Stamen i inni dostawcy kafelków są przełączalni przez TypoScript. Markery są przekazywane do JavaScriptu jako tablica JSON, co pozostaje wydajne także przy 500 i więcej lokalizacjach.

Clustering realizowany jest przez plugin Leaflet.markercluster, który łączy markery przy niskim poziomie zoomu i rozdziela je przy przybliżaniu. Progi clusteringu są konfigurowalne. Wyszukiwanie po kodzie pocztowym lub miejscowości odbywa się po stronie klienta, co działa do 1000 markerów bez wsparcia serwerowego.

Style map można w pełni dostosować: kolory, kroje pisma, szerokości ulic i szczegóły mapy można kontrolować przez konfigurację Tile-Layer i niestandardowy CSS. W porównaniu z Google Maps, którego stylizacja jest ograniczona, Leaflet daje pełną kontrolę nad wyglądem.

Częste problemy dotyczą geocodingu, dostępności serwera kafelków i widoku responsywnego

Problem pierwszy: błędy geocodingu przy nieprecyzyjnych adresach. Nie każdy adres jest poprawnie rozpoznawany przez usługę geocodingu. Szczególnie tereny przemysłowe, nowe osiedla i adresy na obszarach wiejskich dostarczają nieprecyzyjne lub błędne współrzędne. Rozwiązanie: używać automatycznego geocodingu jako pierwszego wypełnienia i sprawdzać współrzędne ręcznie. Rozszerzenie powinno pokazywać okno mapy w backendzie, przez które redaktor może poprawić marker metodą drag-and-drop.

Problem drugi: dostępność serwera kafelków. Standardowy serwer kafelków OpenStreetMap ma politykę Fair Use i przy dużym ruchu może zastosować ograniczanie zapytań (rate limiting). Dla witryn produkcyjnych z ponad 50 000 wyświetleń mapy miesięcznie zaleca się własny serwer kafelków lub komercyjnego dostawcę takiego jak Mapbox czy Maptiler. Koszty wynoszą od 5 do 50 euro miesięcznie, wciąż znacznie poniżej Google Maps.

Problem trzeci: widok responsywny na urządzeniach mobilnych. Mapy na małych ekranach są trudne w obsłudze, ponieważ przybliżanie koliduje z przewijaniem strony. Rozwiązanie: ograniczyć gesty dotykowe na mapie do dwóch palców (wyłączyć scrollWheelZoom i dragging na urządzeniach mobilnych) i udostępnić przycisk “powiększ mapę”, który otwiera mapę w trybie pełnoekranowym.

Leaflet jest przyszłościowy, rozszerzenie TYPO3 trzeba sprawdzić przy v13

Leaflet jako biblioteka JavaScript jest niezależny od wersji TYPO3 i jest aktywnie rozwijany. Rozszerzenie TYPO3, które obejmuje integrację backendową i renderowanie, trzeba sprawdzić przy aktualizacji do v12 lub v13. Zmiany API Extbase w v12 dotyczą klas repozytoriów i konfiguracji persystencji. W Gosign integracje Leaflet migrujemy zwykle przez plugin własny we własnym sitepackage, który bezpośrednio wczytuje bibliotekę Leaflet i pobiera dane lokalizacji z tabeli Extbase lub endpointu JSON. Eliminuje to zależność od rozszerzenia i daje pełną kontrolę nad aktualizacjami. Sama biblioteka Leaflet jest wczytywana przez npm lub CDN i z rozmiarem 39 KB (skompresowane) jest znacznie lżejsza niż Google Maps JavaScript API (ponad 185 KB), co pozytywnie wpływa na czas ładowania stron z mapami.