$wsOrderHistory-Modul lesen Sie die Bestellhistorie des aktuell eingeloggten Kunden und zeigen sie in Ihren Templates an. Damit bauen Sie typische Konto-Funktionen: eine Übersicht aller bisherigen Bestellungen und eine Detailansicht zu einer einzelnen Bestellung (z. B. als Grundlage für eine Nachbestellung).
Da das Modul nur Daten des angemeldeten Kunden liefert, ist außerdem das Zusammenspiel mit dem Account-Modul relevant.
Auf dieser Seite geht es ausschließlich um den lesenden Zugriff auf bereits abgeschlossene Bestellungen im Template. Der Bestellvorgang selbst ist im Bestellablauf beschrieben. Der serverseitige Zugriff auf Bestellungen (z. B. für externe Systeme) erfolgt über die API-Referenz Bestellungen, nicht über dieses Modul.
Grundkonzept
$wsOrderHistory hat keine eigenen Variablen. Sie rufen eine Methode auf, weisen das Ergebnis einer eigenen Template-Variable zu und arbeiten dann mit dieser weiter. Der typische Ablauf:
- Liste laden:
loadList()gibt die Bestellungen des Kunden als Liste zurück. Das Ergebnis weisen Sie z. B.$orderListzu. - Prüfen: Sie prüfen mit
{{ if $orderList }}, ob überhaupt Bestellungen vorliegen. - Auflisten: Sie iterieren über die Liste. Pro Eintrag stehen die Eckdaten (
general.orderId,general.dateTime) bereit. Für Summe und Positionen laden Sie die Bestellung über ihre ID nach. - Detail laden:
load(orderId)lädt die vollständige Einzelbestellung (Adressen, Positionen, Preise).
Nur für eingeloggte Kunden
Beide Methoden liefern nur Daten, wenn ein Kunde angemeldet ist. Ist niemand eingeloggt, erhalten Sie eine leere Rückgabe. Prüfen Sie das Ergebnis deshalb immer mit{{ if ... }}, bevor Sie es ausgeben. Sonst entstehen leere Tabellen oder „tote” HTML-Strukturen. Ob ein Kunde angemeldet ist, ermitteln Sie über das Account-Modul.
Liste und Einzelbestellung im Zusammenspiel
loadList()liefert die Übersicht: eine Liste der Bestellungen. Jeder Eintrag enthält die allgemeinen Eckdaten untergeneral.load(orderId)liefert die Detailansicht einer einzelnen Bestellung mit allen Daten: Positionen (orderList.item), Preise (order), Adressen.
load(). Brauchen Sie schon in der Übersicht Summe oder Positionsanzahl, rufen Sie load() auch dort pro Eintrag auf (siehe Beispiele).
Seitenweises Laden (Paging)
Kunden mit langer Historie können sehr viele Bestellungen haben. Statt alle auf einmal zu laden, ruftloadList() die Daten über den options-Parameter seitenweise ab (Paging). Eine „Seite” ist ein Ausschnitt der Gesamtliste. Sie geben an, welche Seite (page) Sie in welcher Größe (size) möchten, optional mit einer benannten Sortierung (sort). Das hält den Seitenaufbau schlank und ermöglicht eine Blätter-Navigation. Details bei der Methode loadList().
Modulübersicht
Beispiel / Ausschnitt über$wsOrderHistory
"ƒ()" kennzeichnet eine Funktion.
Methoden in der Übersicht
Templates
Die Bestellhistorie lässt sich grundsätzlich in jedem Template laden, wird aber typischerweise im Konto-Bereich des Kunden eingebunden, üblicherweise im Templateaccount/orderHistory.htm. Da beide Methoden nur für eingeloggte Kunden Daten liefern (siehe Grundkonzept), gehört die Ausgabe in einen Bereich, der ohnehin eine Anmeldung voraussetzt.
Variablen
$wsOrderHistory stellt keine eigenen Variablen bereit. Die Bestelldaten liegen in der Template-Variable, der Sie das Ergebnis von loadList() bzw. load() zuweisen (siehe Grundkonzept).
Methoden
$wsOrderHistory.loadList()
Gibt die Bestellungen des aktuell eingeloggten Kunden als Liste zurück, um daraus eine Bestellübersicht zu bauen. Über den optionalen Parameteroptions steuern Sie, welcher Ausschnitt geladen wird: seitenweise (page/size) und in welcher Sortierung (sort).
Signatur$wsOrderHistory.loadList(options)
Rückgabearray. Liste der Bestellungen. Jeder Eintrag trägt unter general die Eckdaten (orderId, dateTime). Leer, wenn kein Kunde eingeloggt ist oder keine Bestellungen vorliegen.
Parameter
Optionen (
options)
Über
page und size blättern Sie durch die Historie. So laden Sie die ersten 100 Bestellungen (Seite 1) bzw. die nächsten 100 (Seite 2, also Einträge 101 bis 200):
general bereit. Für Summe und Positionen laden Sie die Bestellung über load() nach (siehe Beispiele):
dateFmt formatiert den Zeitstempel (ISO-String) in ein lesbares Datum. Der Modifier date darf hier nicht verwendet werden. Er bricht das Rendering ab.
Sortierung über sort
Der Wert von sort ist kein freier Feldname, sondern der Name einer vorab definierten Sortier-Option. Diese legen Sie zuerst in der Konfiguration unter general.orderSortOption an. So sind nur freigegebene, benannte Sortierungen möglich. Das verhindert beliebige Sortierfelder und bündelt die erlaubten Sortierungen zentral.
Eine Sortier-Option hat folgende Felder:
Beispiel-Konfiguration für „neueste zuerst”:
loadList() die 100 neuesten Bestellungen zuerst:
$wsOrderHistory.load()
Gibt eine einzelne Bestellung anhand ihrer Bestell-ID als Map mit allen Bestelldaten zurück (z. B. für eine Detailansicht oder eine Nachbestellung). Signatur$wsOrderHistory.load(orderId)
Rückgabemap- Bestelldaten der angeforderten Bestellung. Leer, wenn kein Kunde eingeloggt ist oder die ID nicht zu einer Bestellung des Kunden gehört.
Parameter
Struktur der Bestell-Map
Die Rückgabe vonload() ist nach Themen in Unter-Maps gegliedert. Weisen Sie das Ergebnis zunächst einer Variable zu (im Folgenden $order) und greifen Sie darüber auf die einzelnen Bereiche zu.
JSON-Struktur (Überblick):
general enthält die allgemeinen Eckdaten der Bestellung:
order enthält Preise, Zahlungs- und Versandart:
customer enthält die Daten zum Besteller:
Weitere Bereiche:
Lieferstatus (deliveryStatus)
Der Bereich deliveryStatus enthält den Lieferstatus der Bestellung. Er ist nur vorhanden, wenn im Admin Interface ein Lieferstatus für die Bestellung gesetzt wurde. Prüfen Sie das Feld deshalb immer mit {{ if $order.deliveryStatus }}, bevor Sie es ausgeben.
Der Lieferstatus wird im Admin Interface unter Bestellungen gepflegt und in zwei Arten unterschieden:
Geltungsbereich (type):
global- Der Status gilt für die gesamte Bestellung (alle Produkte werden in einem Paket geliefert).splitted- Die Bestellung wird in mehreren Paketen geliefert; jedes Paket trägt einen eigenen Status und eine Liste der enthaltenen Positionen.
global: statusType, bei splitted je Paket: deliveryStatusType):
tracking- Es wurden eine Sendungsnummer (trackingNumber) und ein Versanddienstleister (trackingVendorId) hinterlegt.trackingVendorIdentspricht deridder Konfiguration checkout.shipTrack.manual- Ein frei formulierter Statustext wurde im Admin Interface eingetragen.
deliveryStatus wird nur von load() geliefert. Die Einträge aus loadList() enthalten das Feld nicht - laden Sie die Bestellung bei Bedarf über ihre ID nach.
Struktur bei globalem Status mit Tracking-Daten:
splitted):
Beispiel
Lieferstatus einer Bestellung anzeigen. Vor der Anzeige wird über
$wsShipTrack.zipCodeConfirmed() geprüft, ob der Kunde die Postleitzahl der Bestellung bestätigt hat; falls nicht, wird das Bestätigungsformular der Aktion ConfirmZipCode angezeigt.
Ist der Lieferstatus gesetzt und die Postleitzahl bestätigt, wird je nach Konfiguration der manuelle Statustext oder die Tracking-Information angezeigt - bei Paket-Lieferung pro Paket inklusive der enthaltenen Positionen. Solange die Postleitzahl nicht bestätigt ist, erscheint stattdessen das Bestätigungsformular.
Aktionen
Für$wsOrderHistory stehen keine Aktionen zur Verfügung. Für die Bestätigung der Postleitzahl vor Anzeige des Lieferstatus siehe die Aktion ConfirmZipCode des Moduls $wsShipTrack.
Beispiele
Bestellübersicht mit Summe und Positionsanzahl
Lädt die Bestellliste, iteriert über die Einträge und lädt pro Eintrag die vollständige Bestellung nach, um Gesamtpreis (order.total) und Anzahl der Positionen (len(orderList.item)) anzuzeigen. Jede Zeile verlinkt über viewUrl() auf die Detailansicht und hängt die Bestell-ID als Parameter orderHistorySelect an.
Pro Bestellung eine verlinkte Zeile mit Datum, Positionsanzahl und Gesamtpreis. Der Modifier
currency gibt das Währungssymbol bereits mit aus (kein separates currencySymbol nötig). Ist der Kunde nicht eingeloggt oder hat keine Bestellungen, erscheint der Hinweistext.
Eine Bestellung aus der Liste öffnen (Detailansicht)
Schließt den Loop: Die Detailansicht liest die in der Übersicht angehängte Bestell-ID aus dem URL-Parameter, lädt damit die Einzelbestellung und gibt deren Eckdaten samt Positionen aus.Klickt der Kunde in der Übersicht auf eine Bestellung, wird die Seite mit
?wsvc=View&orderHistorySelect=<ID> neu aufgebaut, die Bestellung geladen und mit ihren Positionen angezeigt. Jede Position wird über ihre productId mit $wsProducts.load() zum vollständigen Produkt aufgelöst.
Seitenweise durch viele Bestellungen blättern
Überpage blättern Sie durch lange Historien. Die anzuzeigende Seitennummer holen Sie aus einem URL-Parameter, sodass ein „Weiter”-Link jeweils einen neuen Seitenaufbau mit der nächsten Seite auslöst.
Pro Seitenaufruf werden 20 Bestellungen angezeigt. Der Link lädt jeweils die nächsten 20.
Nach Datum sortieren (neueste zuerst)
Setzt die in der Konfigurationgeneral.orderSortOption angelegte Sortier-Option dateDesc voraus (siehe loadList()). Damit liefert loadList() die neuesten Bestellungen zuerst.
Die 100 neuesten Bestellungen, absteigend nach Bestelldatum sortiert.
Weiterführende Links
- $wsAccount - Account & Adressdaten: um zu prüfen, ob ein Kunde eingeloggt ist, bevor Sie die Historie laden.
- $wsViews - Aktuelle Informationen abrufen: liefert
viewUrl()für die Detail-Verlinkung undcurrent.paramszum Auslesen des ParametersorderHistorySelect. - $wsProducts - Produktdaten: lädt zu einer
productIdausorderList.itemdas vollständige Produkt (Name, Bilder). - $wsShipTrack - Sendungsverfolgung: lädt zu einer Sendungsnummer aus
deliveryStatusdie Tracking-Informationen des Versanddienstleisters und prüft die PLZ-Bestätigung. - general - Allgemeine Shopeinstellungen: hier soll unter
orderSortOptiondie fürsortvorgesehene Sortier-Option angelegt werden (siehe Hinweis beiloadList()). - Bestellablauf: beschreibt, wie eine Bestellung entsteht (Abgrenzung zu dieser Seite).
