> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Produktempfehlungsfunktion per AJAX

> Die Produktweiterempfehlung per AJAX einbinden, sodass Formular und Bestätigung ohne Seitenwechsel in Container nachgeladen werden.

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](https://dokumentation.websale.de/v8s/produktweiterempfehlung/produktempfehlungsfunktion-konventionell.md) · [Templates und Tags für Produktempfehlung](https://dokumentation.websale.de/v8s/produktweiterempfehlung/templates-und-tags-fuer-produktempfehlung.md)

## 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 |

> [!WARNING]
>
> 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](https://dokumentation.websale.de/v8s/materialien/websale-javascript-bibliothek.md)

## 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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](https://dokumentation.websale.de/v8s/referenz/tags/st/seitenzustand-und-navigation.md#die-tags-im-uberblick)

## 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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

> [!WARNING]
>
> 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
// --- 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.

> [!WARNING]
>
> 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](https://dokumentation.websale.de/v8s/materialien/websale-javascript-bibliothek.md)

## 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form action="~FORM-ProductRecmd~" id="ws_prod_recmd_form">
```

> [!WARNING]
>
> 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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](https://dokumentation.websale.de/v8s/materialien/materialien-tracking-schnittstelle.md)

## Verwandte Themen

* Wegweiser: [Produktempfehlungsfunktion konventionell](https://dokumentation.websale.de/v8s/produktweiterempfehlung/produktempfehlungsfunktion-konventionell.md)
* Wegweiser: [Templates und Tags für Produktempfehlung](https://dokumentation.websale.de/v8s/produktweiterempfehlung/templates-und-tags-fuer-produktempfehlung.md)
* Wegweiser: [AJAX-Funktionen](https://dokumentation.websale.de/v8s/templates/ajax-funktionen.md)
* Wegweiser: Beschreibung der Tracking-Schnittstelle


## Related topics

- [Templates und Tags für Produktempfehlung](https://dokumentation.websale.de/v8s/produktweiterempfehlung/templates-und-tags-fuer-produktempfehlung.md)
- [JavaScript und jQuery](https://dokumentation.websale.de/v8s/templates/javascript-und-jquery.md)
- [Template-Typen](https://dokumentation.websale.de/v8s/grundlagen-templates/template-typen.md)
- [WEBSALE JavaScript-Bibliothek](https://dokumentation.websale.de/v8s/materialien/websale-javascript-bibliothek.md)
- [AJAX-Funktionen](https://dokumentation.websale.de/v8s/templates/ajax-funktionen.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.