======================================================================= === Anleitung: Modul „Google Maps | Cover72" (mod_googlemaps) === ======================================================================= Diese Anleitung beschreibt die Installation und Konfiguration des Joomla-Moduls „Google Maps | Cover72". Das Modul bindet eine Google-Maps-Karte zu einer Adresse ein - wahlweise mit einem vorgeschalteten Klick-Schutz, der vor der Zustimmung keine Verbindung zu Google aufbaut. == 1. Voraussetzungen == * Joomla 5 oder 6 * PHP 8.1 oder neuer * Administrator-Zugang zum Backend * Die Datei `mod_googlemaps-.zip` (z. B. `mod_googlemaps-1.0.0.zip`) * Kein Google-Cloud-Konto und kein API-Schlüssel nötig (siehe Abschnitt 4.4) == 2. Installation == 1. Im Backend einloggen und zu System → Installieren → Erweiterungen gehen. 2. Im Reiter „Datei hochladen & installieren" die ZIP-Datei auswählen. 3. Auf „Hochladen & Installieren" klicken. 4. Erfolgsmeldung abwarten – das Modul „Google Maps" ist jetzt installiert. Hinweis: Da es sich um ein reguläres Joomla-Modul handelt (kein Custom-HTML-Code), greift der globale Text-Filter von Joomla hier nicht. Es ist keine Sonderkonfiguration (Editor, Sourcerer o. Ä.) nötig. == 3. Modul anlegen und zuweisen == 1. Zu Inhalte → Website → Module gehen. 2. Auf „Neu" klicken. 3. Im Auswahlfenster „Google Maps" auswählen. 4. Einen Titel vergeben (z. B. „Anfahrt" oder „Standort" – erscheint ggf. je nach Template als Überschrift über der Karte). 5. Unter „Position" die gewünschte Modulposition wählen (abhängig vom Template, z. B. `main-bottom` oder eine Position auf einer Kontakt-Unterseite). 6. Unter dem Reiter „Zuweisung der Menüpunkte" festlegen, auf welchen Seiten das Modul erscheinen soll. 7. Die Inhalte im Reiter „Grundeinstellungen" ausfüllen (siehe Abschnitt 4). 8. Status auf „Veröffentlicht" setzen. 9. Speichern. Alternative Einbindung in einen Artikel oder eine Layout-Position: Mit dem Modul-Kürzel lässt sich die Karte auch direkt im Fließtext eines Artikels platzieren: {loadposition modulposition} (dabei `modulposition` durch die tatsächlich zugewiesene Position ersetzen). == 4. Felder im Backend ausfüllen == Beim Bearbeiten des Moduls gibt es den Reiter „Grundeinstellungen", darin mehrere Themenblöcke (Fieldsets). = 4.1 Grundeinstellungen = * Adresse: Die Adresse oder der Ort, der auf der Karte markiert wird, z. B. „Marktstraße 1, 99830 Treffurt". Dient auch als Ziel des Routen-Buttons und des Links „Bei Google Maps öffnen". Pflichtfeld. * Koordinaten (optional): Überschreibt die Adresse bei der Positionierung der Karte, wenn gültig gesetzt. Format: `Breite,Länge`, z. B. `51.0123,10.4567` – zu finden über Rechtsklick auf den Punkt in Google Maps. Die Adresse bleibt trotzdem als Linkziel und Beschriftung erhalten. * Überschrift: Erscheint über der Karte. Leer lassen, um sie wegzulassen. * Zoom-Stufe: 1 = Weltkarte, 21 = einzelnes Gebäude. 15–17 eignet sich für die meisten Adressen. Vorgabe: 15. * Kartentyp: Straßenkarte, Satellit, Hybrid (Satellit mit Beschriftung) oder Gelände. Satellit und Hybrid/Gelände stehen nur in der klassischen Einbettung ohne API-Schlüssel in voller Auswahl zur Verfügung – mit Schlüssel werden Hybrid und Gelände auf Satellit bzw. Straßenkarte abgebildet. Vorgabe: Straßenkarte. = 4.2 Darstellung = * Höhe (Pixel): Höhe der Karte. Vorgabe: 400. * Breite: Volle Breite (100 %) oder Feste Breite. Vorgabe: volle Breite. * Breite (Pixel): Nur sichtbar, wenn „Feste Breite" gewählt ist. Vorgabe: 600. * Eckenradius (Pixel): Vorgabe: 12. * Schatten: Ein/Aus-Schalter. Vorgabe: Ja. * In Graustufen anzeigen: Die Karte erscheint zunächst schwarz-weiß und wird bei Berührung oder Tastaturfokus farbig – dezenter im Seitenbild, ohne Informationsverlust. Vorgabe: Nein. * Akzentfarbe: Balken vor der Überschrift und Vorgabefarbe des Routen-Buttons. Die Schriftfarbe von Button und Klick-Schutz-Button wird automatisch für guten Kontrast gewählt (helle Schrift auf dunklem Button, dunkle Schrift auf hellem Button). Vorgabe: `#1A1A1A`. = 4.3 Routen-Button = * Routen-Button anzeigen: Verlinkt auf die Routenplanung von Google Maps zur konfigurierten Adresse bzw. den Koordinaten – öffnet Google Maps in einem neuen Tab, unabhängig davon, ob die Karte selbst schon geladen wurde. Vorgabe: Ja. * Beschriftung: Eigener Button-Text. Vorgabetext: „Route berechnen". * Farbe: Leer lassen für die Akzentfarbe. Die Schriftfarbe wird automatisch für guten Kontrast gewählt. = 4.4 Erweiterte Einbindung = * Google-Maps-API-Schlüssel: Optional. Leer lassen für die klassische Einbettung ohne Schlüssel (funktioniert ohne Google-Cloud-Konto und reicht für die meisten Adress-Karten). Mit Schlüssel wird stattdessen die offizielle Maps Embed API verwendet. Google gewährt dafür ein kostenloses monatliches Kontingent, danach fallen Kosten an – Details unter developers.google.com/maps/documentation/embed/usage-and-billing. Der Schlüssel erscheint im Quelltext der Seite; in der Google Cloud Console daher unbedingt auf die eigene(n) Domain(s) per HTTP-Referrer einschränken. = 4.5 Datenschutz (Klick-Schutz) = * Klick-Schutz aktivieren: 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. Ohne Klick-Schutz wird die Karte sofort beim Seitenaufruf eingebettet. Vorgabe: Ja. * Überschrift im Hinweis: Vorgabetext: „Google Maps". * Hinweistext: HTML ist erlaubt (z. B. Links, Absätze). Vorgabetext: „Beim Laden der Karte wird eine Verbindung zu Servern von Google in den USA hergestellt und Ihre IP-Adresse dorthin übertragen. Weitere Informationen entnehmen Sie der Datenschutzerklärung von Google." * Beschriftung des Buttons: Vorgabetext: „Karte laden". * Menüeintrag der Datenschutzerklärung: Hat Vorrang vor der freien Adresse darunter. * … oder freie Adresse: Nur wenn oben kein Menüeintrag gewählt ist. Auch relative Pfade der eigenen Seite möglich. * Linktext: Vorgabetext: „Datenschutzerklärung". * Zustimmung merken: Gar nicht (bei jedem Seitenaufruf erneut fragen) / Für den Besuch (sessionStorage) / Dauerhaft in diesem Browser (localStorage). Gilt nur für dieses Modul auf dieser Seite, nicht website-weit. Vorgabe: für den Besuch. Zusätzlich bietet das Modul unabhängig vom Klick-Schutz-Status immer einen Link „Karte stattdessen bei Google Maps öffnen" – dieser funktioniert auch ohne JavaScript und ohne dass zuvor eine Google-Ressource geladen wurde. = 4.6 Erweitert = * Alternatives Layout: Falls zusätzliche Layout-Varianten installiert werden, hier auswählbar. Standardmäßig nicht nötig. * Modulklassen-Suffix: Für erfahrene Anwender: fügt der Karte eine zusätzliche CSS-Klasse hinzu, falls eigenes CSS ergänzt werden soll. Im Normalfall leer lassen. * CSS und JavaScript einbinden: „Beim Modul" (Vorgabe) funktioniert in jedem Template, auch wenn dessen `` bereits vor den Modulpositionen geschlossen wird. „Im Seitenkopf" nutzt stattdessen den Web-Asset-Manager. * Zwischenspeicherung (Caching): Die Ausgabe hängt nicht vom Besucher ab und kann daher gefahrlos zwischengespeichert werden. Vorgabe: globale Einstellung verwenden. == 5. Datenschutz im Überblick == Das Modul ist bewusst so gebaut, dass vor einer Zustimmung nichts von Google geladen wird: * Ohne Klick auf „Karte laden" entsteht keine Verbindung zu Google-Servern, kein Cookie, kein Tracking-Pixel. * Erst der Klick lädt die eigentliche Karte (klassische Einbettung oder, mit API-Schlüssel, die Maps Embed API). * Der Link „Karte stattdessen bei Google Maps öffnen" führt direkt zu Google Maps, ohne dass zuvor irgendetwas eingebettet wurde – funktioniert auch bei deaktiviertem JavaScript. * „Zustimmung merken" ist rein clientseitig (sessionStorage/localStorage) und gilt nur für die jeweilige Modul-Instanz auf der jeweiligen Seite. Wird die Karte über die eigene Datenschutzerklärung angesprochen, sollte dort der Hinweis auf Google Maps (Google Ireland Limited bzw. Google LLC) samt Verweis auf Google's Datenschutzerklärung nicht fehlen, sobald das Modul im Einsatz ist. == 6. 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`. Kein jQuery, keine externen Abhängigkeiten vor der Zustimmung, Icons als Inline-SVG. == 7. Häufige Fragen / Fehlerbehebung == Die Karte erscheint gar nicht, nur ein Hinweis in Rot. → Das erscheint nur für Administratoren, wenn weder eine Adresse noch Koordinaten hinterlegt sind. Im Reiter „Grundeinstellungen" die Adresse eintragen. Der Klick-Schutz-Hinweis erscheint jedes Mal neu, obwohl schon einmal zugestimmt wurde. → Im Reiter „Datenschutz" prüfen, ob „Zustimmung merken" auf „Gar nicht" steht. Für ein dauerhaftes Merken „Dauerhaft in diesem Browser" wählen. Der Routen-Button fehlt. → Im Reiter „Routen-Button" prüfen, ob „Routen-Button anzeigen" auf Ja steht. Der Button ist auf meinem Hintergrund kaum zu sehen. → Wird bei Akzent- bzw. Button-Farbe kein eigener Wert gesetzt, wählt das Modul die Schriftfarbe automatisch nach Kontrast. Wurde eine feste Farbe gewählt, sollte sie sich deutlich vom Kartenhintergrund abheben. Ich möchte statt der klassischen Einbettung die offizielle Google-API nutzen. → Im Reiter „Erweiterte Einbindung" einen Google-Maps-API-Schlüssel eintragen (Google Cloud Console, Embed API aktivieren, Schlüssel per HTTP-Referrer auf die eigene(n) Domain(s) einschränken). Satellit/Hybrid/Gelände lässt sich nicht wie erwartet auswählen. → Mit hinterlegtem API-Schlüssel bildet die offizielle Embed API Hybrid und Gelände auf Satellit bzw. Straßenkarte ab. Ohne Schlüssel (klassische Einbettung) stehen alle vier Kartentypen zur Verfügung. Die Karte ist zu klein oder zu groß. → Höhe (Pixel) im Reiter „Darstellung" anpassen. Für eine feste statt volle Breite „Feste Breite" wählen und die Breite (Pixel) eintragen. == 8. Update auf eine neuere Version == Um eine aktualisierte Version des Moduls einzuspielen: 1. System → Installieren → Erweiterungen öffnen. 2. Die neue ZIP-Datei hochladen und installieren – Joomla erkennt automatisch, dass es sich um ein Update handelt, und ersetzt die vorhandenen Dateien. 3. Alle bereits gespeicherten Backend-Einstellungen (Adresse, Farben, Texte) bleiben dabei erhalten, da sie separat in der Datenbank gespeichert sind. == 9. Updates == Das Modul meldet sich bei einem eigenen Update-Server, sodass neue Fassungen unter System → Aktualisieren → Erweiterungen angeboten werden – Einstellungen bleiben dabei erhalten. Über „Änderungen anzeigen" ist vorher einsehbar, was die neue Version bringt. Einmalig nötig: Bei einer bereits bestehenden Installation ohne diese Funktion (z. B. einer sehr frühen Fassung) kennt Joomla den Update-Server noch nicht. Die aktuelle ZIP muss daher ein letztes Mal von Hand über System → Installieren → Erweiterungen eingespielt werden. Alle späteren Updates laufen dann automatisch. Sollte eine neue Version nicht sofort erscheinen: Joomla merkt sich die Abfrage einige Stunden. Unter System → Aktualisieren → Erweiterungen → Optionen lässt sich der Zwischenspeicher leeren, danach „Aktualisierungen suchen". == 10. Versionen == * 1.0.0: Erste Veröffentlichung. Bei Rückfragen zur Konfiguration oder für Layout-Anpassungen kann der Code in `tmpl/default.php` (Darstellung), `src/Helper/GooglemapsHelper.php` (Datenverarbeitung) und `mod_googlemaps.xml` (Backend-Formularfelder) eingesehen werden.