AJAX-Funktionen - WEBSALE Dokumentation

Vorausgesetzt wird, dass Sie mit den Templates Ihres Shops und mit der WEBSALE JavaScript-Bibliothek vertraut sind. Normalerweise öffnet der Browser mit jedem Klick auf einen Link eine Folgeseite. Bei einer Integration per AJAX (Asynchronous JavaScript and XML) ruft der Klick stattdessen eine JavaScript-Funktion auf. Diese startet die AJAX-Kommunikation und verhindert, dass der Browser die Seite neu lädt. Der angeforderte Inhalt wird nachgeladen und dynamisch in die bestehende Seite eingefügt. Der Nutzen liegt im geringeren Datenverkehr. Ein Inhalt wird erst geholt, wenn er gebraucht wird, beispielsweise wenn der Käufer auf den Reiter “Frage zum Produkt” klickt. Der Rest der Seite bleibt unangetastet.

AJAX setzt voraus, dass der Kunde in seinem Browser JavaScript aktiviert hat. Ist JavaScript deaktiviert, wird die Seite wie gewohnt komplett neu aufgebaut. Ihre Templates müssen deshalb in beiden Zuständen funktionieren. Wie Sie das erreichen, zeigt der Abschnitt zu den WS-Ajax-Sektionen.

Voraussetzungen

Für alle AJAX-Integrationen brauchen Sie die WEBSALE JavaScript-Systembibliothek samt zugehöriger Design-Komponente, mindestens in der Version 1.8.1. Die Systembibliothek bringt die AJAX-Funktionen mit, in der Design-Komponente hinterlegen Sie Ihre eigenen Reaktionen auf Erfolg und Fehler. Wegweiser: JavaScript und jQuery Materialien: WEBSALE JavaScript-Bibliothek

Setzen Sie die Tracking-Schnittstelle zusammen mit AJAX ein, beachten Sie die dortigen Hinweise zu AJAX-basierten Funktionen. Da bei einem AJAX-Aufruf kein vollständiger Seitenaufbau stattfindet, greifen Tracking-Aufrufe sonst nicht.Wegweiser: Beschreibung der Tracking-Schnittstelle

So läuft ein AJAX-Aufruf ab

Bevor Sie den ersten Link bauen, lohnt sich ein Blick auf den Ablauf. Er ist bei Inhalten und Formularen derselbe und erklärt, warum Sie vier JavaScript-Funktionen angeben.

Der Kunde klickt auf einen Link oder einen Button. Die aufgerufene Funktion unterbindet den normalen Seitenwechsel.
Vor dem Absenden der Anfrage läuft die startFunction. Hier blenden Sie typischerweise einen Layer mit einer Ladegrafik ein.
Die Anfrage geht an WEBSALE V8s. Dort wird das angeforderte Template erzeugt und zurückgegeben.
Kommt keine Antwort zustande, beispielsweise weil die Internetverbindung abgebrochen ist oder ein Timeout eintritt, läuft die failureFunction.
Kommt eine Antwort zurück, entscheidet ihr Inhalt: Bei Erfolg läuft der successCallback, meldet WEBSALE V8s dagegen einen Fehler, läuft der errorCallback.
Bei Erfolg trägt die Systembibliothek den zurückgegebenen Inhalt automatisch in die Anzeigebereiche Ihrer Seite ein.

Der Unterschied zwischen failureFunction und errorCallback ist wichtig für Ihre Fehlermeldungen. Die failureFunction steht für einen Kommunikationsfehler, bei dem der Shop gar nicht geantwortet hat. Der errorCallback steht für eine Antwort des Shops, die einen Fehler meldet, beispielsweise ein nicht gefundenes Template. Der angeforderte Inhalt wird über das Tag WS-LoadTpl angefordert, gegebenenfalls in Kombination mit WS-ExternInclude, FORM-Template oder FORM-SSLTemplate.

Inhalte per AJAX nachladen

Der einfachere der beiden Fälle ist das Nachladen von Inhalten, beispielsweise einer Informationsseite hinter einem Reiter. Er besteht aus vier Schritten: Link bauen, Bibliothek einbinden, Anzeigebereich anlegen, Zieltemplate vorbereiten.

Schritt 1: Link erstellen

Der Link ruft die Funktion ws_AJAXloadTemplate auf. Das return davor verhindert, dass der Browser zusätzlich dem Link folgt.

<a onclick="return ws_AJAXloadTemplate('Link', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   Linkname
</a>

Die Bedeutung der einzelnen Parameter finden Sie im Abschnitt “Syntax der Funktionen”. Referenz: WS-LoadTpl()

Schritt 2: Systembibliothek und Design-Komponente einbinden

Binden Sie die Systembibliothek samt Design-Komponente ein. Haben Sie das bereits getan, prüfen Sie die Version.

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

Erweitern Sie anschließend die Design-Komponente um die vier Funktionen, die Sie im Link angegeben haben. Ohne diese Funktionen bricht der Aufruf ab, sobald die Systembibliothek sie aufrufen will.

// Läuft, bevor die AJAX-Anfrage abgesetzt wird, beispielsweise für eine Ladeanzeige
function startFunction()
{
   ...
}

// Läuft, wenn das Nachladen erfolgreich war
function successCallback()
{
   ...
}

// Läuft, wenn WEBSALE V8s einen Fehler zurückgegeben hat
function errorCallback()
{
   ...
}

// Läuft, wenn die AJAX-Kommunikation fehlgeschlagen ist, beispielsweise bei unterbrochener Internetverbindung
function failureFunction()
{
   ...
}

Schritt 3: Anzeigebereiche definieren

Auf dem Template mit dem Link legen Sie einen oder mehrere Anzeigebereiche an. In sie wird der nachgeladene Inhalt eingesetzt. Verwenden Sie dafür ein beliebiges HTML-Element mit einer ID. Die ID ist die Verbindung zum Zieltemplate und muss deshalb eindeutig sein.

<div id="inhalt1">
   ...
</div>
<div id="inhalt2">
   ...
</div>

Schritt 4: WS-Ajax-Sektionen im Zieltemplate anlegen

WEBSALE V8s gibt das Template zurück, das der Link aufruft. Damit die Systembibliothek weiß, welcher Teil davon wohin gehört, teilen Sie das Zieltemplate in WS-Ajax-Sektionen. Der Sektionsname besteht aus dem Präfix WS-Ajax- und der ID des Anzeigebereichs. Auf diesem Weg tauschen Sie mit einem einzigen Aufruf auch mehrere Bereiche gleichzeitig aus.

<WS-Ajax-inhalt1>
   ....
</WS-Ajax-inhalt1>

<WS-Ajax-inhalt2>
   ....
</WS-Ajax-inhalt2>

Referenz: WS-Ajax-”ID” Ist dasselbe Template auch über einen normalen Aufruf erreichbar, klammern Sie die Sektionsmarken mit ST-Ajax. Ohne diese Klammerung stünden die Marken bei einem normalen Aufruf sichtbar im Quelltext.

{ST-Ajax}<WS-Ajax-inhalt1>{/ST-Ajax}
    ....
{ST-Ajax}</WS-Ajax-inhalt1>{/ST-Ajax}

{ST-Ajax}<WS-Ajax-inhalt2>{/ST-Ajax}
    ....
{ST-Ajax}</WS-Ajax-inhalt2>{/ST-Ajax}

Referenz: ST-Ajax

Formulare per AJAX nachladen und absenden

Ein Formular durchläuft denselben Ablauf, allerdings zweimal: einmal beim Nachladen des Formulars und einmal beim Absenden. Für das Absenden gibt es eine eigene Funktion, weil dabei die Feldinhalte mitgeschickt werden. Das Ergebnis des Absendens hängt von der Eingabe ab. Ist sie fehlerhaft, gibt WEBSALE V8s das Formular erneut zurück, samt Fehlermeldungen. War sie gültig, kommt die Bestätigungsseite des Formulars zurück. In beiden Fällen landet die Antwort im selben Anzeigebereich.

Schritt 1: Formular per Link nachladen

Das Nachladen des Formulars unterscheidet sich nicht vom Nachladen eines Inhalts.

<a onclick="return ws_AJAXloadTemplate('Link', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   Linkname
</a>

Schritt 2: Formular und Submit-Button anpassen

Integrieren Sie Ihr form-Element wie gewohnt und vergeben Sie eine ID. Über diese ID findet die Funktion beim Absenden die Feldinhalte. Am Submit-Button ergänzen Sie den Aufruf von ws_AJAXsendFormTemplate.

<form action="~FORM-Template(Ihr Template)~" method="post" id="form">
   ...
   <input type="submit" value="absenden" onclick="return ws_AJAXsendFormTemplate('form', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   ...
</form>

Schritt 3: Design-Komponente erweitern

Binden Sie die Systembibliothek samt Design-Komponente ein und ergänzen Sie dort dieselben vier Funktionen wie beim Nachladen von Inhalten. Beide Aufrufe können sich dieselben Funktionen teilen oder eigene verwenden.

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

Schritt 4: Anzeigebereich definieren

Auf dem Template, das das Formular aufnehmen soll, legen Sie einen Anzeigebereich mit einer ID an.

<div id="formular">
   ...
</div>

Schritt 5: WS-Ajax-Sektion anlegen

Das Formular-Template umschließen Sie mit einer WS-Ajax-Sektion, deren Name auf die ID des Anzeigebereichs endet.

<WS-Ajax-formular>
   ....
</WS-Ajax-formular>

Wird dasselbe Formular auch ohne AJAX verwendet, klammern Sie die Sektionsmarken wieder mit ST-Ajax. Denken Sie dabei an den Button: Ohne AJAX darf er den Funktionsaufruf nicht tragen, sonst würde das Formular gar nicht abgeschickt.

{ST-Ajax}<WS-Ajax-formular>{/ST-Ajax}
    ....

   {ST-Ajax}
   <input type="submit" value="absenden" onclick="return ws_AJAXsendFormTemplate('form', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   {/ST-Ajax}

   {!ST-Ajax}
   <input type="submit" value="absenden">
   {/!ST-Ajax}

{ST-Ajax}</WS-Ajax-formular>{/ST-Ajax}

Syntax der Funktionen

Beide Funktionen erwarten dieselben Parameter, nur der erste unterscheidet sich. Beim Nachladen ist es der Link, beim Absenden die ID des Formulars. Achten Sie auf die Anführungszeichen: startFunction und failureFunction werden als Funktionsobjekt übergeben, also ohne Anführungszeichen und ohne Klammern. successCallback und errorCallback werden dagegen als Zeichenkette übergeben, die den vollständigen Funktionsaufruf inklusive Klammern enthält.

ws_AJAXloadTemplate

<a onclick="return ws_AJAXloadTemplate('Link', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">
   Linkname
</a>

Parameter	Typ	Pflicht	Beschreibung
`link`	Zeichenkette	ja	Link zur gewünschten Seite, erzeugt über `WS-LoadTpl()` oder `WS-SSLLoadTpl()`
`charset`	Zeichenkette	ja	Zeichensatz des Shops, dynamisch setzbar über `~WS-Charset~`
`startFunction`	Funktionsobjekt	ja	Läuft vor dem Start der AJAX-Kommunikation, beispielsweise für eine Ladeanzeige
`failureFunction`	Funktionsobjekt	ja	Läuft, wenn die Kommunikation fehlschlägt, beispielsweise bei fehlender Verbindung oder Timeout
`successCallback`	Zeichenkette	ja	Funktionsaufruf für den Erfolgsfall
`errorCallback`	Zeichenkette	ja	Funktionsaufruf, wenn die Kommunikation gelang, WEBSALE V8s aber einen Fehler zurückgibt
`additionalPayload`	Zeichenkette	nein	Zusätzliche Parameter-Wert-Paare in URL-codierter Form, beispielsweise `otp1=my_param&otp2=my_second_param`

Referenz: WS-Charset

ws_AJAXsendFormTemplate

<input type="submit" value="absenden" onclick="return ws_AJAXsendFormTemplate('form', 'charset', startFunction, failureFunction, 'successCallback()', 'errorCallback()');">

Parameter	Typ	Pflicht	Beschreibung
`formid`	Zeichenkette	ja	ID des Formulars, dessen Felder gesendet werden
`charset`	Zeichenkette	ja	Zeichensatz des Shops
`startFunction`	Funktionsobjekt	ja	Läuft vor dem Start der AJAX-Kommunikation, beispielsweise für eine Ladeanzeige
`failureFunction`	Funktionsobjekt	ja	Läuft, wenn die Kommunikation fehlschlägt, beispielsweise bei fehlender Verbindung oder Timeout
`successCallback`	Zeichenkette	ja	Funktionsaufruf für den Erfolgsfall
`errorCallback`	Zeichenkette	ja	Funktionsaufruf, wenn die Kommunikation gelang, WEBSALE V8s aber einen Fehler zurückgibt
`additionalPayload`	Zeichenkette	nein	Zusätzliche Parameter-Wert-Paare in URL-codierter Form, beispielsweise `otp1=my_param&otp2=my_second_param`

Mögliche Integrationen mit AJAX

Die folgenden Inhalte und Features lassen sich mit den beschriebenen Funktionen per AJAX einbinden. Die jeweiligen Seiten zeigen die Integration am konkreten Beispiel, samt der dort verwendeten Funktionsnamen.

Informationsseiten per AJAX nachladen
Formulare per AJAX nachladen und absenden
Schnellanmeldung für Bestandskunden

​Voraussetzungen

​So läuft ein AJAX-Aufruf ab

​Inhalte per AJAX nachladen

​Schritt 1: Link erstellen

​Schritt 2: Systembibliothek und Design-Komponente einbinden

​Schritt 3: Anzeigebereiche definieren

​Schritt 4: WS-Ajax-Sektionen im Zieltemplate anlegen

​Formulare per AJAX nachladen und absenden

​Schritt 1: Formular per Link nachladen

​Schritt 2: Formular und Submit-Button anpassen

​Schritt 3: Design-Komponente erweitern

​Schritt 4: Anzeigebereich definieren

​Schritt 5: WS-Ajax-Sektion anlegen

​Syntax der Funktionen

​ws_AJAXloadTemplate

​ws_AJAXsendFormTemplate

​Mögliche Integrationen mit AJAX

Voraussetzungen

So läuft ein AJAX-Aufruf ab

Inhalte per AJAX nachladen

Schritt 1: Link erstellen

Schritt 2: Systembibliothek und Design-Komponente einbinden

Schritt 3: Anzeigebereiche definieren

Schritt 4: WS-Ajax-Sektionen im Zieltemplate anlegen

Formulare per AJAX nachladen und absenden

Schritt 1: Formular per Link nachladen

Schritt 2: Formular und Submit-Button anpassen

Schritt 3: Design-Komponente erweitern

Schritt 4: Anzeigebereich definieren

Schritt 5: WS-Ajax-Sektion anlegen

Syntax der Funktionen

ws_AJAXloadTemplate

ws_AJAXsendFormTemplate

Mögliche Integrationen mit AJAX