Store-Locator JTL-Shop Plugin

Store-Locator

Beschreibung

Der Store-Locator ist ein Plugin für JTL-Shop, das eine interaktive Google Maps-basierte Filialsuche ermöglicht. Kunden können Ihre Filialen, Geschäfte oder Abholstationen auf einer Karte visualisieren, nach Standorten suchen und die nächstgelegenen Stores finden.

Das Plugin bietet eine vollständige Verwaltung im Backend mit Import/Export-Funktionen und eine benutzerfreundliche Suchfunktion im Frontend.

Anwendungsbereiche

Der Store-Locator eignet sich für folgende Szenarien:

Einzelhandelsgeschäfte mit mehreren Filialen
Franchise-Unternehmen mit verschiedenen Standorten
Abholstationen und Paketshops
Service-Partner und Händlernetze
Showrooms und Ausstellungsräume
Werkstätten und Servicezentren
Restaurant-Ketten und Gastronomie
Temporäre Pop-Up-Stores mit Zeitraumbegrenzung

Hauptfunktionen

Interaktive Google Maps-Integration
Verwaltung beliebig vieler Store-Standorte
Automatische Geocodierung von Adressen
Umkreissuche nach PLZ, Ort oder Adresse
Entfernungsberechnung zu Stores
Filterung nach Ländern
Zeitraumbegrenzung für temporäre Stores
CSV-Import und Export
Eigenes Marker-Icon anpassbar
Responsive Darstellung

Voraussetzungen

Wichtig: Das Plugin benötigt einen gültigen Google Maps API-Schlüssel mit aktivierten APIs.

Folgende Google APIs müssen aktiviert sein:

Maps JavaScript API
Places API
Distance Matrix API
Geocoding API

Google Maps API-Schlüssel erhalten

Besuchen Sie die Google Cloud Console
Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus
Aktivieren Sie die erforderlichen APIs (siehe Liste oben)
Erstellen Sie unter "APIs & Services → Credentials" einen neuen API-Schlüssel
Beschränken Sie den API-Schlüssel auf Ihre Domain (empfohlen)

Store-Verwaltung

Einen neuen Store anlegen

Navigieren Sie zu: Plugins → SALEPIX Store-Locator → Adressen
Klicken Sie auf "Neuer Store" oder "Hinzufügen"
Füllen Sie die Store-Informationen aus
Speichern Sie den Store

Store-Felder

Feld	Pflicht	Beschreibung
Firma / Unternehmen	Ja	Name der Firma oder des Unternehmens (z.B. "Filiale München Innenstadt")
Inhaber	Nein	Name des Inhabers oder Ansprechpartners (optional)
Straße	Ja	Straßenname
Straßennummer	Ja	Hausnummer
PLZ	Ja	Postleitzahl
Stadt	Ja	Stadt oder Ort
Land	Ja	Land (z.B. "Deutschland", "Österreich")
Webseite	Nein	Website des Stores (optional)
Öffnungszeiten	Nein	Öffnungszeiten (mehrzeilig möglich, z.B. "Mo-Fr: 9-18 Uhr")
Status	Ja	Aktiv / Inaktiv
Latitude	Automatisch	Wird automatisch per Geocoding ermittelt
Longitude	Automatisch	Wird automatisch per Geocoding ermittelt
Start-Datum	Nein	Ab wann ist der Store sichtbar (optional)
End-Datum	Nein	Bis wann ist der Store sichtbar (optional)

Die Koordinaten (Latitude/Longitude) werden automatisch aus der eingegebenen Adresse ermittelt (Geocoding).

CSV-Import und Export

Stores exportieren

Klicken Sie in der Store-Liste auf "CSV Export"
Die CSV-Datei wird heruntergeladen

Stores importieren

Erstellen Sie eine CSV-Datei mit den Store-Daten
Klicken Sie auf "CSV Import"
Wählen Sie die CSV-Datei aus
Die Stores werden importiert und Koordinaten automatisch ermittelt

CSV-Format

Die CSV-Datei muss folgende Spalten enthalten (Trennzeichen: Semikolon):

name;owner;street;number;zip_code;city;country;url;opening_hours;active;start_date;end_date

Beispiel:

Filiale München;Max Mustermann;Marienplatz;1;80331;München;Deutschland;https://example.de;Mo-Fr: 9-18 Uhr;1;; Filiale Berlin;Anna Schmidt;Alexanderplatz;5;10178;Berlin;Deutschland;;Sa: 10-14 Uhr;1;2024-01-01;2024-12-31

active: 1 = Aktiv, 0 = Inaktiv
opening_hours: Mehrzeiliger Text mit \n für Zeilenumbrüche möglich
Datumsformat: JJJJ-MM-TT
Leere Felder sind erlaubt (außer Pflichtfelder)

Frontend-Nutzung

Store-Locator Seite aufrufen

Nach der Installation ist der Store-Locator automatisch unter folgender URL erreichbar:

https://ihr-shop.de/store-locator

Die Seite kann auch im Menü verlinkt werden (Standard: hidden-Gruppe).

Suchfunktionen

Kunden können Stores auf zwei Arten finden:

1. Übersicht ohne Suche

Zeigt alle aktiven Stores auf der Karte mit dem konfigurierten Mittelpunkt und Zoom-Level.

2. Umkreissuche mit Google Places Autocomplete

Intelligente Adresssuche mit Autocomplete-Funktion:

Autocomplete-Eingabe: Beginnen Sie mit der Eingabe einer Adresse, PLZ oder Stadt
Vorschläge: Google Places zeigt passende Vorschläge während der Eingabe
Auswahl: Wählen Sie einen Vorschlag aus der Liste
Radius: Passen Sie den Suchradius an (Standard: 20 km)
Ergebnis: Stores im gewählten Umkreis werden angezeigt und nach Entfernung sortiert

Tipp: Das Land wird automatisch erkannt - Sie müssen es nicht separat auswählen!

Anzeige im Frontend

Die Store-Locator Seite zeigt:

Interaktive Google Maps Karte mit roten Markern
Liste aller gefundenen Stores
Store-Details: Firma, Inhaber, Adresse, Öffnungszeiten, Webseite
Bei Umkreissuche: Entfernung als blauer Badge (z.B. "5,25 km")
Map-Icon: Rotes Icon rechts oben - Click zentriert Karte auf Store
Hover-Effekt: Mouseover auf Marker hebt Store in Liste hervor
Öffnungszeiten: Werden mit Uhr-Icon angezeigt (falls vorhanden)

Tipp: Klicken Sie auf das rote Map-Icon bei einem Store, um die Karte auf diesen Store zu zentrieren!

Zeitraumbegrenzung für temporäre Stores

Stores können zeitlich begrenzt angezeigt werden (z.B. für Pop-Up-Stores oder saisonale Filialen).

Start-Datum

Store wird erst ab dem angegebenen Datum angezeigt.

Beispiel: Pop-Up-Store ab 01.12.2024 → Start-Datum: 2024-12-01

End-Datum

Store wird nur bis zum angegebenen Datum angezeigt.

Beispiel: Weihnachtsmarkt-Stand bis 31.12.2024 → End-Datum: 2024-12-31

Kombination

Start- und End-Datum können kombiniert werden.

Beispiel: Temporärer Store vom 01.06.2024 bis 31.08.2024 (Sommer-Saison)

Stores ohne Datumsangaben sind dauerhaft sichtbar (solange Status "Aktiv").

Kartenmarkierung anpassen

Marker-Größe

Die Größe der Kartenmarkierung kann in den Einstellungen angepasst werden:

Marker-Größe (px): Standard 32 Pixel
Empfohlene Werte: 24 (klein), 32 (standard), 40 (groß), 48 (sehr groß)
Gilt für Standard-Icons und Custom-Icons

Standard Google Maps Marker (farbig)

Sie können vordefinierte Google Maps Marker in verschiedenen Farben verwenden:

Farbe	URL
Rot (Standard)	`https://maps.google.com/mapfiles/ms/icons/red-dot.png`
Blau	`https://maps.google.com/mapfiles/ms/icons/blue-dot.png`
Grün	`https://maps.google.com/mapfiles/ms/icons/green-dot.png`
Gelb	`https://maps.google.com/mapfiles/ms/icons/yellow-dot.png`
Orange	`https://maps.google.com/mapfiles/ms/icons/orange-dot.png`
Lila	`https://maps.google.com/mapfiles/ms/icons/purple-dot.png`
Pink	`https://maps.google.com/mapfiles/ms/icons/pink-dot.png`

Eigenes Marker-Icon

Das Standard-Marker-Icon kann durch ein eigenes ersetzt werden:

Laden Sie Ihr Icon-Bild hoch (z.B. via FTP oder Medienverwaltung)
Kopieren Sie die vollständige URL zum Bild
Tragen Sie die URL in den Einstellungen ein: "Kartenmarkierung anpassen"
Passen Sie ggf. die Marker-Größe an
Speichern Sie die Einstellungen

Icon-Anforderungen

Format: PNG, SVG oder JPG
Empfohlene Größe: 24×24 px bis 64×64 px
Transparenter Hintergrund (bei PNG) empfohlen
Dateigröße: maximal 100 KB

Das Icon wird automatisch auf die konfigurierte Größe skaliert.

Backend-Features

Quick-Access Buttons

In der Store-Verwaltung stehen folgende Buttons zur Verfügung:

Frontend anzeigen: Öffnet die Store-Locator Seite im Frontend (neues Fenster)
Seite verwalten: Öffnet die Link-Verwaltung zur Bearbeitung von Überschrift, Meta-Angaben und SEO-URL (neues Fenster)

Sprachvariablen

Im Tab "Sprachvariablen" können Sie folgende Texte anpassen:

spLocatorSearchPlaceholder: Platzhalter im Suchfeld (Standard: "Bitte PLZ, Ort oder Adresse eingeben")
spLocatorSubmitButton: Text auf dem Such-Button (Standard: "Finden")

Beide Texte können für Deutsch und Englisch separat konfiguriert werden.

Design-Einstellungen

Suchen-Button Stil: 12 Bootstrap-Styles zur Auswahl (primary, secondary, success, danger, etc.)
Marker-Größe: Pixel-Größe der Kartenmarkierungen (Standard: 32)
Kartenmarkierung URL: Custom Icon oder Google Maps farbige Pins

Technische Details

Geocoding

Die automatische Ermittlung der Koordinaten erfolgt durch die Google Geocoding API:

Bei Speichern eines Stores wird die Adresse geocodiert
Latitude und Longitude werden automatisch gespeichert
Bei Adressänderung erfolgt erneutes Geocoding

Entfernungsberechnung

Bei Umkreissuche wird die Entfernung zwischen Suchposition und Store berechnet:

Berechnung per Haversine-Formel (Luftlinie)
Ergebnis in Kilometern mit deutscher Formatierung (Komma als Dezimaltrennzeichen)
Sortierung nach Entfernung (nächster zuerst)

Datenbank

Die Stores werden in folgender Tabelle gespeichert:

xplugin_salepix_storelocator_shop

Felder: id, name, owner, street, number, zip_code, city, country, url, opening_hours, active, latitude, longitude, start_date, end_date

Frontend-Link

Der Store-Locator ist als Frontend-Link registriert:

Datei: frontend/storelocator.php
Template: frontend/template/storelocator.tpl
SEO-URL: /store-locator
Linkgruppe: hidden (kann über die Link-Verwaltung angepasst werden)

Fehlerbehebung

Problem: Karte wird nicht angezeigt

Lösung:

Prüfen Sie, ob der API-Schlüssel korrekt eingegeben wurde
Prüfen Sie, ob alle erforderlichen APIs aktiviert sind
Prüfen Sie die Browser-Konsole auf Fehlermeldungen
Prüfen Sie, ob das API-Kontingent nicht überschritten wurde

Problem: Koordinaten werden nicht ermittelt

Lösung:

Prüfen Sie, ob die Geocoding API aktiviert ist
Prüfen Sie, ob die Adresse vollständig und korrekt ist
Prüfen Sie das Shop-Errorlog

Problem: Umkreissuche findet keine Stores

Lösung:

Erhöhen Sie den Suchradius
Prüfen Sie, ob Stores als "aktiv" markiert sind
Prüfen Sie die Datumsangaben (Start/End-Datum)
Prüfen Sie, ob die Suchadresse korrekt geocodiert wurde

Kosten und API-Limits

Wichtig: Google Maps APIs sind kostenpflichtig, bieten aber ein monatliches Gratis-Kontingent.

Typische Kosten (Stand 2024, kann sich ändern):

Maps JavaScript API: $7 pro 1.000 Kartenaufrufe (monatlich $200 Guthaben)
Geocoding API: $5 pro 1.000 Anfragen
Distance Matrix API: $5 pro 1.000 Anfragen

Für kleine bis mittlere Shops reicht das kostenlose Kontingent meist aus. Überwachen Sie die Nutzung in der Google Cloud Console.

Performance-Tipps

Geocoding erfolgt nur beim Speichern, nicht bei jedem Seitenaufruf
Koordinaten werden in der Datenbank gecacht
Begrenzen Sie die Anzahl der Stores auf der Karte (empfohlen: max. 100-200)
Verwenden Sie kleine Icon-Dateien (max. 50 KB)