# Google Maps | Cover72 (mod_googlemaps) 1.2.0

Google-Maps-Modul für **Joomla 5 und 6** (Site-Modul, PHP 8.1+).

## Installation

1. `mod_googlemaps-1.2.0.zip` unter **System → Erweiterungen installieren** hochladen.
2. **Inhalt → Website-Module → Neu → Google Maps**.
3. Adresse eintragen, Modulposition wählen, Menüzuweisung setzen, veröffentlichen.

## Einstellungen

**Grundeinstellungen**
- *Adresse* – wird auf der Karte markiert und dient als Ziel des Routen-Buttons und des
  Links „Bei Google Maps öffnen".
- *Koordinaten (optional)* – überschreibt die Adresse bei der Positionierung, wenn im
  Format `Breite,Länge` gültig gesetzt (z. B. `51.0123,10.4567`). Die Adresse bleibt
  trotzdem als Linkziel und Beschriftung erhalten.
- *Überschrift*, *Zoom-Stufe* (1–21), *Kartentyp* (Straßenkarte, Satellit, Hybrid, Gelände).

**Darstellung**
- Höhe, Breite (volle Breite oder fest), Eckenradius, Schatten.
- *In Graustufen anzeigen* – die Karte ist zunächst schwarz-weiß und wird bei Berührung
  oder Tastaturfokus farbig.
- *Akzentfarbe* – Balken vor der Überschrift und Vorgabefarbe des Routen-Buttons. Die
  Schriftfarbe wird automatisch für guten Kontrast gewählt.

**Routen-Button**
- Verlinkt auf die Routenplanung von Google Maps in einem neuen Tab, unabhängig davon,
  ob die Karte selbst schon geladen wurde. Eigene Beschriftung und Farbe möglich.

**Info-Karte**
- Blendet eine eigene kleine Karte mit Bild, Titel, Adresse und Kontaktdaten (Telefon,
  E-Mail, Webseite) über der Kartenansicht ein – wahlweise in einer der vier Ecken, Vorgabe
  oben links. Standardmäßig ausgeschaltet, im Reiter „Info-Karte" aktivierbar.
- Das ist eine eigene Karte des Moduls – nicht die Infobox, die Google manchmal selbst
  automatisch in die Karte einblendet, wenn die hinterlegte Adresse als Unternehmen bekannt
  ist. Diese Google-eigene Box lässt sich grundsätzlich nicht mit eigenem Bild oder eigenen
  Kontaktdaten füllen; wer das möchte, aktiviert stattdessen die Info-Karte dieses Moduls.
- Zusätzlich lassen sich ein Routen-Button (nutzt Beschriftung und Ziel des Routen-Buttons
  unterhalb der Karte) und ein WhatsApp-Button (eigenes Nummernfeld, sonst die oben
  eingetragene Telefonnummer) direkt in der Info-Karte einblenden.

**Erweiterte Einbindung**
- Ohne API-Schlüssel nutzt das Modul die klassische Einbettung – kein Google-Cloud-Konto
  nötig, reicht für die meisten Adress-Karten.
- Mit hinterlegtem *API-Schlüssel* wird stattdessen die offizielle Google Maps Embed API
  verwendet. Google gewährt ein kostenloses monatliches Kontingent, danach fallen Kosten
  an. Den Schlüssel in der Google Cloud Console unbedingt per HTTP-Referrer auf die
  eigene(n) Domain(s) einschränken.

**Datenschutz**
- *Klick-Schutz*: Bevor die Karte eine Verbindung zu Google aufbaut, zeigt das Modul
  zunächst nur einen Platzhalter mit Hinweistext und einem Button „Karte laden". Vor dem
  Klick wird keinerlei Ressource von Google geladen – kein iframe, kein Bild, kein Cookie.
  Ein zusätzlicher Link „Karte stattdessen bei Google Maps öffnen" funktioniert auch ohne
  JavaScript.
- Überschrift, Hinweistext (HTML erlaubt) und Buttonbeschriftung frei setzbar; ein
  deutscher Standardtext ist hinterlegt.
- Link zur Datenschutzerklärung wahlweise als Menüeintrag oder freie Adresse.
- Zustimmung merken: gar nicht / für den Besuch / dauerhaft. Gilt nur für dieses Modul
  auf dieser Seite.
- *Mit cover72 Cookie Consent abgleichen* – ist auf derselben Seite die Erweiterung
  „cover72 Cookie Consent" aktiv und dort die Kategorie „Karten" bereits akzeptiert, lädt
  die Karte direkt, ganz ohne den eigenen Klick-Schutz. Wird die Zustimmung erst später
  erteilt, lädt eine noch wartende Karte automatisch nach, ohne dass die Seite neu geladen
  werden muss. Ohne diese Erweiterung oder ohne Zustimmung ändert sich nichts. Vorgabe: an.
- Abschaltbar – dann wird die Karte sofort beim Seitenaufruf eingebettet.

## Technische Hinweise

- Kein jQuery, keine externen Abhängigkeiten vor der Zustimmung, Icons als Inline-SVG.
- Farben laufen über CSS-Custom-Properties (`--gmap-accent`, `--gmap-height` …) und lassen
  sich im Template überschreiben.
- Modul-Caching ist standardmäßig aktiv, da die Ausgabe nicht vom Besucher abhängt.

## Sicherheit

Adresse und Koordinaten laufen durch serverseitige Validierung, Farbwerte und der optionale
API-Schlüssel werden geprüft und bereinigt, der Datenschutzlink ist auf http/https und
seiteninterne Ziele eingeschränkt. Alle Ausgaben laufen durch `htmlspecialchars`.

## Updates

Das Modul meldet sich bei einem eigenen Update-Server, sodass neue Fassungen unter
**System → Aktualisieren → Erweiterungen** angeboten werden – Einstellungen bleiben dabei
erhalten. Bei einer bereits bestehenden Installation ohne diese Funktion muss die aktuelle
ZIP einmal von Hand über **System → Installieren → Erweiterungen** eingespielt werden,
danach laufen alle weiteren Updates automatisch.

Lizenz: GPL-2.0-or-later.