Produktempfehlungsfunktion per AJAX - WEBSALE Dokumentation

Bei der konventionellen Integration verlässt der Käufer die Produktseite oder bekommt ein Popup-Fenster. Bei der AJAX-Integration bleibt er, wo er ist: Formular und Bestätigung werden in einen Container auf der Seite nachgeladen. Der Preis dafür ist zusätzliche Arbeit an den Templates und an der Designkomponente. Diese Seite beschreibt genau diese Zusatzarbeit. Die Funktion selbst, ihre Konfiguration und ihre Tags stehen auf der Seite zur konventionellen Integration. Bauen Sie die Funktion zuerst konventionell und ergänzen Sie AJAX erst danach. Sie haben dann eine funktionierende Grundlage und wissen bei einem Fehler, ob er aus dem Formular oder aus der AJAX-Kette kommt. Wegweiser: Produktempfehlungsfunktion konventionell · Templates und Tags für Produktempfehlung

Voraussetzungen

Voraussetzung
JavaScript im Browser des Käufers	aktiviert
WEBSALE JavaScript-Systembibliothek	mindestens Version 1.8.1
WEBSALE Designkomponente	mit den acht Funktionen aus Schritt 4

Ohne aktives JavaScript funktioniert die AJAX-Variante nicht. Sorgen Sie deshalb dafür, dass der auslösende Link auch ohne JavaScript zum Ziel führt, indem Sie im href den konventionellen Link hinterlegen. Der Käufer landet dann auf der normalen Empfehlungsseite statt vor einem Link, der nichts tut.

Materialien: WEBSALE JavaScript-Bibliothek

Wie der Ablauf aussieht

Ein Klick auf ein beliebiges Element, beispielsweise einen Reiter oder einen Link, ruft eine JavaScript-Funktion auf. Diese unterbindet den normalen Seitenaufruf und startet stattdessen die AJAX-Anfrage. WEBSALE V8s beantwortet diese Anfrage mit demselben Template, das auch beim konventionellen Aufruf zum Einsatz kommt. Der Unterschied liegt in der Verpackung: Das Template ist in benannte Bereiche aufgeteilt, und die Systembibliothek setzt den Inhalt jedes Bereiches in den div-Container mit demselben Namen.

<WS-Ajax-ID1>
   ...
</WS-Ajax-ID1>

<WS-Ajax-ID2>
   ...
</WS-Ajax-ID2>

Die ID hinter WS-Ajax- wählen Sie frei, sie muss nur mit der ID des Zielcontainers übereinstimmen. Weil Sie beliebig viele Bereiche anlegen können, lassen sich mit einer Anfrage mehrere Stellen der Seite gleichzeitig austauschen. Weil dasselbe Template auch konventionell aufgerufen wird, dürfen die Bereichsmarkierungen dort nicht im Quelltext landen. Dafür gibt es ST-AJAX. Die Klammerung zeigt ihren Inhalt nur, wenn der Aufruf tatsächlich eine AJAX-Anfrage war.

{ST-AJAX}
   <WS-Ajax-ID1>
{/ST-AJAX}

   ...

{ST-AJAX}
   </WS-Ajax-ID1>
{/ST-AJAX}

Geklammert werden nur die beiden Markierungen, nicht der Inhalt dazwischen. Der Inhalt wird in beiden Fällen gebraucht. Referenz: ST-AJAX

Die aufrufende Seite vorbereiten

Die ersten vier Schritte gelten für das Template, von dem aus der Käufer die Empfehlung startet, in aller Regel die Produktdetailansicht.

Schritt 1: Die Bibliotheken einbinden

<head>
   ...
   <script type="text/javascript" src="/$WS/ws_sysdata/js/ws-system-1.8.1.js"></script>
   <script type="text/javascript" src="../js/ws-design-1.8.1.js"></script>
   ...
</head>

Die erste Datei ist die WEBSALE JavaScript-Systembibliothek, die zweite Ihre Designkomponente. Prüfen Sie die Versionsnummern gegen die Bibliothek, die Sie tatsächlich einsetzen. Version 1.8.1 ist die Untergrenze für diese Funktion.

Schritt 2: Die Container anlegen

Drei Container nehmen die drei möglichen Zustände auf: Es lädt, es ist etwas schiefgegangen, oder es ist da.

<div id="ws_prodrecmd_loading" style="display:none;">
   <!-- Ladeanzeige waehrend der AJAX-Anfrage -->
</div>

<div id="ws_prodrecmd_error" style="display:none;">
   Es ist ein Fehler aufgetreten. Bitte versuchen Sie es noch einmal.
</div>

<div id="ws_prodrecmd_content">
   <!-- hier landen Formular und Bestaetigung -->
</div>

Der Inhaltscontainer trägt hier die ID ws_prodrecmd_content. Genau diese ID brauchen Sie in Schritt 5 und in Schritt 8 wieder, denn sie verbindet die Container mit den Bereichen in den Templates.

Lade- und Fehlercontainer stehen im Ausgangszustand auf display:none. Ohne das sieht der Käufer beim Seitenaufruf eine Ladegrafik und eine Fehlermeldung, bevor er überhaupt etwas getan hat.

Schritt 3: Den Auslöser setzen

Auf das Element, das die Empfehlung öffnen soll, kommt ein onclick-Ereignis. WS-ProductRecmdLink liefert die Zieladresse, WS-JSEncoding bereitet sie für die Verwendung in JavaScript auf.

<a href="~WS-ProductRecmdLink~"
   onclick="return ws_AJAXloadProductRecmd('~WS-JSEncoding($WS-ProductRecmdLink$)~','~WS-Charset~');">
   Produkt weiterempfehlen
</a>

Die Schreibweise $WS-ProductRecmdLink$ innerhalb der Klammern ist die Art, ein Tag als Parameter an ein anderes Tag zu übergeben. Ohne diese Verschachtelung stünde im JavaScript ein unmaskierter Link, der bei einem Sonderzeichen den Aufruf zerlegt. Im href steht derselbe Link ohne Verschachtelung. Er greift, wenn JavaScript nicht zur Verfügung steht.

Schritt 4: Die Funktionen der Designkomponente füllen

Acht Funktionen bilden die beiden Vorgänge ab, das Nachladen des Formulars und das Absenden. Jeder Vorgang hat vier Zustände: Start, Erfolg, fachlicher Fehler und Kommunikationsfehler.

Vorgang	Start	Erfolg	Fehler	Kommunikationsfehler
Formular laden	`ws_AJAXloadProductRecmdStart`	`ws_AJAXloadProductRecmdResponseSuccess`	`ws_AJAXloadProductRecmdResponseError`	`ws_AJAXloadProductRecmdError`
Empfehlung absenden	`ws_AJAXsendProductRecmdStart`	`ws_AJAXsendProductRecmdResponseSuccess`	`ws_AJAXsendProductRecmdResponseError`	`ws_AJAXsendProductRecmdError`

Alle acht tun dasselbe: Sie blenden von den drei Containern den passenden ein und die beiden anderen aus.

// --- Formular nachladen ---

// vor dem Absetzen der Anfrage: Ladeanzeige
function ws_AJAXloadProductRecmdStart()
{
   $('#ws_prodrecmd_error').hide();
   $('#ws_prodrecmd_content').hide();
   $('#ws_prodrecmd_loading').show();
}

// Nachladen erfolgreich: Inhalt zeigen
function ws_AJAXloadProductRecmdResponseSuccess()
{
   $('#ws_prodrecmd_error').hide();
   $('#ws_prodrecmd_loading').hide();
   $('#ws_prodrecmd_content').show();
}

// Nachladen nicht erfolgreich: Fehler zeigen
function ws_AJAXloadProductRecmdResponseError()
{
   $('#ws_prodrecmd_loading').hide();
   $('#ws_prodrecmd_content').hide();
   $('#ws_prodrecmd_error').show();
}

// AJAX-Kommunikation fehlgeschlagen, beispielsweise bei abgebrochener Verbindung
function ws_AJAXloadProductRecmdError()
{
   $('#ws_prodrecmd_loading').hide();
   $('#ws_prodrecmd_content').hide();
   $('#ws_prodrecmd_error').show();
}

// --- Empfehlung absenden ---

function ws_AJAXsendProductRecmdStart()
{
   $('#ws_prodrecmd_error').hide();
   $('#ws_prodrecmd_content').hide();
   $('#ws_prodrecmd_loading').show();
}

function ws_AJAXsendProductRecmdResponseSuccess()
{
   $('#ws_prodrecmd_error').hide();
   $('#ws_prodrecmd_loading').hide();
   $('#ws_prodrecmd_content').show();
}

function ws_AJAXsendProductRecmdResponseError()
{
   $('#ws_prodrecmd_loading').hide();
   $('#ws_prodrecmd_content').hide();
   $('#ws_prodrecmd_error').show();
}

function ws_AJAXsendProductRecmdError()
{
   $('#ws_prodrecmd_loading').hide();
   $('#ws_prodrecmd_content').hide();
   $('#ws_prodrecmd_error').show();
}

ResponseError und Error unterscheiden sich in der Ursache: Beim ersten hat der Shop geantwortet, aber nicht wie erwartet. Beim zweiten kam die Anfrage gar nicht durch. Sie dürfen dasselbe tun, aber sobald Sie zwei verschiedene Meldungstexte ausgeben wollen, brauchen Sie beide getrennt.

Ein fachlicher Fehler in der Eingabe des Käufers, beispielsweise eine falsche E-Mail-Adresse, ist keiner dieser Fälle. Dabei antwortet der Shop erfolgreich mit dem erneut gefüllten Formular, und der Erfolgsfall greift. Die Fehlermeldung zum Feld steht im Formular selbst.

Die Beispiele verwenden jQuery. Setzen Sie eine andere Bibliothek oder gar keine ein, ersetzen Sie die Zeilen entsprechend. An den Funktionsnamen ändert sich nichts, denn die ruft die Systembibliothek auf. Referenz: WEBSALE JavaScript-Systembibliothek

Das Formular-Template erweitern

Die folgenden drei Schritte betreffen das Template, das im Abschnitt <Templates> hinter ProductRecmd steht.

Schritt 5: Den AJAX-Bereich anlegen

Legen Sie um das Eingabeformular einen Bereich, dessen Name die Container-ID aus Schritt 2 trägt.

{ST-AJAX}
   <WS-Ajax-ws_prodrecmd_content>
{/ST-AJAX}

   <!-- Eingabeformular fuer die Produktweiterempfehlung -->
   ...

{ST-AJAX}
   </WS-Ajax-ws_prodrecmd_content>
{/ST-AJAX}

Schritt 6: Dem Formular eine ID geben

Die AJAX-Funktion braucht das Formular, um seine Felder auszulesen. Sie findet es über die ID.

<form action="~FORM-ProductRecmd~" id="ws_prod_recmd_form">

Das Tag heißt FORM-ProductRecmd, ausgeschrieben. Eine Abkürzung wie FORM-ProdRecmd gibt es nicht, das Formular hätte dann kein Ziel.

Schritt 7: Die Schaltfläche umstellen

Beim AJAX-Aufruf bekommt die Schaltfläche ein onclick-Ereignis, beim konventionellen Aufruf nicht. Beide Fälle stehen nebeneinander im Template, jeweils geklammert.

{ST-AJAX}
   <input type="submit" value="absenden"
          onclick="return ws_AJAXsendProductRecmd('ws_prod_recmd_form', '~WS-Charset~');">
{/ST-AJAX}

{!ST-AJAX}
   <input type="submit" value="absenden">
   <a href="javascript:window.close();">Fenster schließen</a>
{/!ST-AJAX}

Der erste Parameter ist die Formular-ID aus Schritt 6. Weicht sie ab, findet die Funktion das Formular nicht und schickt eine leere Empfehlung ab. Der Link zum Schließen des Fensters steht bewusst nur im Gegenzweig. Bei der AJAX-Variante gibt es kein Popup-Fenster, das sich schließen ließe.

Das Bestätigungs-Template erweitern

Schritt 8: Denselben AJAX-Bereich anlegen

Im Template hinter ProductRecmdConfirm legen Sie einen Bereich mit derselben ID an.

{ST-AJAX}
   <WS-Ajax-ws_prodrecmd_content>
{/ST-AJAX}

   <!-- Bestaetigung: vielen Dank fuer Ihre Empfehlung -->
   ...

{ST-AJAX}
   </WS-Ajax-ws_prodrecmd_content>
{/ST-AJAX}

Dass hier dieselbe ID steht, ist kein Versehen. Nach dem erfolgreichen Absenden soll die Bestätigung genau dort erscheinen, wo vorher das Formular stand. Der Shop liefert dafür einfach das andere Template, und die Systembibliothek tauscht den Inhalt desselben Containers aus.

Tracking-Schnittstelle

Verwenden Sie die Tracking-Schnittstelle, beachten Sie deren Hinweise zu AJAX-basierten Funktionen. Ein per AJAX nachgeladener Inhalt löst keinen Seitenaufruf aus und wird deshalb nicht von selbst gezählt. Wegweiser: Beschreibung der Tracking-Schnittstelle

​Voraussetzungen

​Wie der Ablauf aussieht

​Die aufrufende Seite vorbereiten

​Schritt 1: Die Bibliotheken einbinden

​Schritt 2: Die Container anlegen

​Schritt 3: Den Auslöser setzen

​Schritt 4: Die Funktionen der Designkomponente füllen

​Das Formular-Template erweitern

​Schritt 5: Den AJAX-Bereich anlegen

​Schritt 6: Dem Formular eine ID geben

​Schritt 7: Die Schaltfläche umstellen

​Das Bestätigungs-Template erweitern

​Schritt 8: Denselben AJAX-Bereich anlegen

​Tracking-Schnittstelle

​Verwandte Themen

Voraussetzungen

Wie der Ablauf aussieht

Die aufrufende Seite vorbereiten

Schritt 1: Die Bibliotheken einbinden

Schritt 2: Die Container anlegen

Schritt 3: Den Auslöser setzen

Schritt 4: Die Funktionen der Designkomponente füllen

Das Formular-Template erweitern

Schritt 5: Den AJAX-Bereich anlegen

Schritt 6: Dem Formular eine ID geben

Schritt 7: Die Schaltfläche umstellen

Das Bestätigungs-Template erweitern

Schritt 8: Denselben AJAX-Bereich anlegen

Tracking-Schnittstelle

Verwandte Themen