2. Start
  4. Versand Countdown Plugin ...
  6. Dokumentation
  8. Dokumentation

Dokumentation

Shipping Countdown für JTL-Shop 5 – Dokumentation

Inhaltsverzeichnis

  1. Einleitung
  2. Features
  3. Systemvoraussetzungen
  4. Installation
  5. Erste Einrichtung
  6. Konfiguration
  1. Anzeigeregeln im Frontend
  2. Sprachvariablen
  3. Technische Details
  4. Fehlerbehebung
  5. Häufig gestellte Fragen

Einleitung

Shipping Countdown ist ein Plugin für JTL-Shop 5, das auf der Artikeldetailseite einen Live-Countdown anzeigt. Der Countdown informiert Kunden in Echtzeit darüber, wie lange sie noch bestellen können, damit ihr Artikel noch am selben Tag versendet wird.

Durch die gezielte Darstellung von Dringlichkeit direkt am Kaufbutton können Conversion Rate und Umsatz gesteigert werden. Das Plugin ist flexibel konfigurierbar, mehrsprachig und berücksichtigt automatisch Feiertage sowie Wochenenden.

Features

  • Live-Countdown mit Stunden, Minuten und Sekunden
  • Beliebig viele Countdowns für verschiedene Versandklassen
  • Versandklassen-Zuordnung über Select2 – jede Klasse nur einmal verwendbar
  • Flexible Cutoff-Zeiten pro Countdown (z.B. 14:00 Uhr Standard, 10:00 Uhr Spedition)
  • Restzeit-Steuerung: Anzeige erst X Stunden vor der Cutoff-Zeit oder ab Beginn des Versandtages
  • Intelligente Anzeigeregeln: nur bei Lagerbestand, nur bei Kind-Artikeln oder Artikeln ohne Variationskombination
  • Automatische Feiertagsberechnung für deutsche Bundesländer via Yasumi
  • Eigene Feiertage im Backend pflegbar
  • Jährlicher Cronjob für automatischen Feiertags-Import am 01.01.
  • Individuelle Positionierung über CSS-Selektor und Einfügemethode
  • Mehrsprachigkeit über JTL-Sprachvariablen
  • Automatisches Ausblenden nach Ablauf der Frist

Systemvoraussetzungen

  • JTL-Shop 5.6 oder höher
  • PHP 8.1 oder höher
  • MySQL/MariaDB Datenbank
  • Schreibrechte für das Plugin-Verzeichnis

Installation

Schritt 1: Dateien kopieren

Kopieren Sie das Plugin-Verzeichnis xv_shipping_countdown in den plugins/-Ordner Ihrer JTL-Shop-Installation.

Code
[shop-root]/plugins/xv_shipping_countdown/

Schritt 2: Plugin installieren

  1. Melden Sie sich im JTL-Shop Backend an.
  2. Navigieren Sie zu Plugin-Verwaltung.
  3. Suchen Sie nach Shipping Countdown.
  4. Klicken Sie auf Installieren.

Schritt 3: Cache leeren

Leeren Sie den Template-Cache und den Objekt-Cache im JTL-Shop Backend.

Schritt 4: Plugin aktivieren

Aktivieren Sie das Plugin in der Plugin-Verwaltung.

Erste Einrichtung

Nach der Installation finden Sie das Plugin-Menü unter Plugin > Shipping Countdown. Es besteht aus drei Bereichen:

  1. Allgemeine Einstellungen
  2. Countdowns
  3. Feiertage

Konfiguration

Allgemeine Einstellungen

Unter Allgemeine Einstellungen können Sie die Positionierung der Countdown-Box im Frontend festlegen.

phpQuery Selektor

Der CSS-Selektor bestimmt, an welches Element die Countdown-Box angefügt wird.

  • Standardwert: #add-to-cart
  • Beispiele:
  • #add-to-cart – Warenkorb-Button
  • .product-actions – Container um den Warenkorb-Button
  • .product-detail-buy – Kauf-Bereich

Hinweis: Wenn der Selektor nicht gefunden wird, wird die Box nicht angezeigt. Prüfen Sie bei individuellen Templates den korrekten Selektor mit den Entwicklertools Ihres Browsers.

Einfüge-Methode

Bestimmt, wie die Box relativ zum Selektor eingefügt wird:

  • before – vor dem Element
  • after – nach dem Element (Standard)
  • append – innerhalb am Ende des Elements
  • prepend – innerhalb am Anfang des Elements

Für die Standardposition unterhalb des Warenkorb-Buttons verwenden Sie:

  • Selektor: #add-to-cart
  • Methode: after

Countdowns verwalten

Unter Countdowns legen Sie beliebig viele Countdown-Konfigurationen an.

Feld: Name

Interne Bezeichnung des Countdowns. Wird nur im Backend verwendet.

Feld: Letzte Bestellzeit

Uhrzeit im Format HH:MM, bis zu der eine Bestellung noch am selben Tag versendet wird.

  • Beispiel: 14:00 für Standard-Versand
  • Beispiel: 10:00 für Spedition

Hinweis: Die tatsächliche Versandfähigkeit hängt von Ihren internen Prozessen ab. Das Plugin visualisiert nur die konfigurierte Grenze.

Feld: Max. Reststunden

Bestimmt, ab wann der Countdown im Frontend angezeigt wird.

  • 0 – Countdown wird ab Beginn des Versandtages angezeigt (ab 00:00 Uhr)
  • 5 – Countdown wird erst 5 Stunden vor der Cutoff-Zeit angezeigt
  • 12 – Countdown wird 12 Stunden vor der Cutoff-Zeit angezeigt

Tipp: Ein Wert von 2 oder 3 Stunden erzeugt eine besonders starke Dringlichkeit kurz vor der Versandgrenze.

Feld: Versandklassen

Wählen Sie eine oder mehrere Versandklassen aus, für die der Countdown gelten soll.

  • Jede Versandklasse kann nur einem Countdown zugeordnet werden.
  • Bereits verwendete Versandklassen werden in der Auswahl ausgegraut und mit dem zugehörigen Countdown gekennzeichnet.
  • Artikel ohne Versandklasse erhalten keinen Countdown.

Feld: Aktiv

Nur aktive Countdowns werden im Frontend berücksichtigt. Inaktive Countdowns bleiben gespeichert, werden aber nicht angezeigt.

Feiertage verwalten

Unter Feiertage verwalten Sie Tage, an denen keine Lieferung/kein Versand erfolgt.

Eigener Feiertag hinzufügen

  1. Geben Sie ein Datum im Format TT.MM.JJJJ ein.
  2. Geben Sie einen Namen ein (z.B. "Betriebsurlaub").
  3. Klicken Sie auf Hinzufügen.

Eigene Feiertage werden bei der Versandtagsberechnung automatisch berücksichtigt.

Bundesland für automatische Feiertage

Wählen Sie ein deutsches Bundesland aus, dessen gesetzliche Feiertage automatisch berücksichtigt werden sollen.

  • Bayern
  • Baden-Württemberg
  • Berlin
  • Brandenburg
  • Bremen
  • Hamburg
  • Hessen
  • Niedersachsen
  • Mecklenburg-Vorpommern
  • Nordrhein-Westfalen
  • Rheinland-Pfalz
  • Saarland
  • Sachsen
  • Sachsen-Anhalt
  • Schleswig-Holstein
  • Thüringen

Hinweis: Die Feiertage werden über die Bibliothek Yasumi berechnet und können für das aktuelle Jahr manuell oder automatisch per Cronjob importiert werden.

Feiertage für das aktuelle Jahr importieren

Mit dem Button Feiertage für das aktuelle Jahr importieren werden alle gesetzlichen Feiertage des gewählten Bundeslandes für das laufende Jahr in die Datenbank übernommen. Bereits vorhandene Feiertage bleiben erhalten.

Automatischer jährlicher Import

Das Plugin registriert einen Cronjob vom Typ plugin:xv_shipping_countdown:holiday_import. Dieser läuft täglich um 02:00 Uhr und importiert die Feiertage automatisch am 01.01. jedes Jahres für das neue Jahr.

Wichtig: Damit der Cronjob funktioniert, muss der JTL-Shop Cronjob-Dienst eingerichtet und aktiv sein.

Anzeigeregeln im Frontend

Der Countdown wird nur angezeigt, wenn alle folgenden Bedingungen erfüllt sind:

  1. Artikel ist auf Lager (fLagerbestand > 0)
  2. Artikel hat eine Versandklasse, für die ein aktiver Countdown konfiguriert ist
  3. Artikel ist ein Kind-Artikel oder hat keine Variationskombination
  • Vater-Artikel (Artikel mit Variationen) zeigen keinen Countdown
  • Kind-Artikel oder einfache Artikel zeigen den Countdown
  1. Aktuelles Datum ist ein Versandtag (kein Wochenende, kein Feiertag)
  2. Restzeit liegt innerhalb des konfigurierten Fensters
  • z.B. bei "Max. Reststunden = 5" nur 5 Stunden vor der Cutoff-Zeit

Wenn die Restzeit abläuft, wird die Box automatisch ausgeblendet.

Sprachvariablen

Alle Frontend-Texte können über JTL-Sprachvariablen angepasst werden.

xvshippingcountdown_text

Text der Countdown-Box.

Platzhalter:

  • {time} – wird durch den Zeit-Text ersetzt (z.B. "0 Stunden, 52 Minuten und 42 Sekunden")
  • {today} – wird durch "heute" ersetzt

Beispiel Deutsch:

Code
Bestellen Sie in den nächsten {time} und es wird noch {today} versendet.

Beispiel Englisch:

Code
Order within the next {time} and it will be shipped {today}.

Weitere Sprachvariablen

VariableVerwendung
xv_shipping_countdown_hourEinzahl Stunde
xv_shipping_countdown_hoursMehrzahl Stunden
xv_shipping_countdown_minuteEinzahl Minute
xv_shipping_countdown_minutesMehrzahl Minuten
xv_shipping_countdown_secondEinzahl Sekunde
xv_shipping_countdown_secondsMehrzahl Sekunden
xv_shipping_countdown_andBindewort (z.B. "und")
xv_shipping_countdown_todayWort für "heute"

Technische Details

Datenbanktabellen

Das Plugin legt folgende Tabellen an:

  • xplugin_xv_shipping_countdown – Countdown-Konfigurationen
  • xplugin_xv_shipping_countdown_class – Zuordnung Countdown ↔ Versandklasse
  • xplugin_xv_shipping_countdown_holiday – Eigene Feiertage

Cronjob

  • Typ: plugin:xv_shipping_countdown:holiday_import
  • Frequenz: täglich um 02:00 Uhr
  • Aktion: Importiert gesetzliche Feiertage am 01.01. jedes Jahres

Frontend-Injection

Die Countdown-Box wird über den Hook HOOK_SMARTY_OUTPUTFILTER und phpQuery in die Artikeldetailseite eingefügt. Es sind keine Template-Anpassungen erforderlich.

CSS-Klassen

  • .shipping-countdown-box – äußerer Container
  • .shipping-countdown-text – Text-Container
  • .countdown-highlight – hervorgehobene Zeitangaben und das Wort "heute"

Sie können das Aussehen über eigene CSS-Regeln anpassen, indem Sie diese Klassen überschreiben.

Fehlerbehebung

Der Countdown wird nicht angezeigt

  1. Prüfen Sie, ob das Plugin aktiv ist.
  2. Prüfen Sie, ob der Artikel auf Lager ist.
  3. Prüfen Sie, ob dem Artikel eine Versandklasse zugeordnet ist.
  4. Prüfen Sie, ob für diese Versandklasse ein aktiver Countdown existiert.
  5. Prüfen Sie den konfigurierten phpQuery Selektor und die Einfüge-Methode.
  6. Prüfen Sie mit den Browser-Entwicklertools, ob der Selektor im Template vorhanden ist.
  7. Leeren Sie den Template-Cache.

Der Countdown wird am falschen Tag angezeigt

  1. Prüfen Sie die konfigurierten Feiertage.
  2. Prüfen Sie, ob das korrekte Bundesland ausgewählt ist.
  3. Führen Sie den Import der Feiertage erneut aus.

Der Countdown erscheint nicht zur erwarteten Uhrzeit

  1. Prüfen Sie die Letzte Bestellzeit des Countdowns.
  2. Prüfen Sie die Max. Reststunden.
  3. Vergewissern Sie sich, dass die Serverzeit korrekt eingestellt ist.

Admin-Menü zeigt Fehler

  1. Leeren Sie den Admin-Template-Cache (admin/templates_c/).
  2. Deinstallieren und reinstallieren Sie das Plugin.

Häufig gestellte Fragen

Kann ich mehrere Countdowns für dieselbe Versandklasse anlegen?

Nein. Jede Versandklasse kann nur einem Countdown zugeordnet werden. Dies verhindert Konflikte bei der Anzeige.

Was passiert, wenn ein Artikel mehrere Versandklassen hat?

Das Plugin verwendet die Versandklasse, die direkt am Artikel hinterlegt ist (kVersandklasse).

Werden Wochenenden berücksichtigt?

Ja. Samstage und Sonntage werden automatisch als Nicht-Versandtage behandelt.

Kann ich das Aussehen der Countdown-Box anpassen?

Ja. Überschreiben Sie die CSS-Klassen .shipping-countdown-box, .shipping-countdown-text und .countdown-highlight in Ihrem Template.

Funktioniert das Plugin mit Child-Templates?

Ja. Solange der konfigurierte CSS-Selektor im Template vorhanden ist, funktioniert das Plugin mit allen JTL-Shop 5 Templates.

Ist das Plugin mehrsprachig?

Ja. Alle Texte werden über JTL-Sprachvariablen verwaltet.

Support

Bei Fragen oder Problemen wenden Sie sich bitte an den Support.

© X-Volution

Wie können wir helfen?