Verhalten anpassen

Fehlerbehandlung

Falls Sie eine eigene Fehlerbehandlungs-Routine implementieren möchten, dann können Sie das Property errorHandler bzw. failureHandler dazu benutzen, um auf eine spezielle Weise mit Fehlern umzugehen.

Die errorHandler Funktion wird aufgerufen, falls OXOMI einen Fehler zurückliefert. Die failureHandler Funktion wird angewendet, falls während der Verarbeitung der abgerufenen Daten im Browser ein Fehler auftritt.

Parameter Beschreibung

errorHandler

Ermöglicht es eine Funktion zu übergeben, welche bei einem serverseitigen Fehler aufgerufen wird.

Diese bekommt ein Objekt mit den folgenden Eigenschaften übergeben:

Parameter	Beschreibung
method	Name der Teilfunktion von OXOMI, die angesprochen wurde
uri	Die URI des entsprechenden API-Aufrufs
args	Die Parameter, welche an den Server gesendet wurden
json	Die vom Server erzeugte Antwort

Siehe Öffentliche API für eine Beschreibung der erzeugten Antwortstruktur. Wenn diese Funktion true zurück gibt, wird keine weitere Verarbeitung durchgeführt.

failureHandler

Ermöglicht eine Funktion zu übergeben, welche bei einem Ausnahmefehler im Client aufgerufen wird.

Diese bekommt ein Objekt mit den folgenden Eigenschaften übergeben:

Parameter	Beschreibung
method	Name der Teilfunktion von OXOMI, die angesprochen wurde
uri	Die URI des entsprechenden API-Aufrufs
args	Die Parameter, welche an den Server gesendet wurden
json	Die vom Server erzeugte Antwort
error	Der Fehler als JavaScript Exception

Hinweis: Beide Properties müssen während der Initialisierung definiert werden.

Beispiel:

// OXOMI initialisieren und Fehlerbehandlung definieren
oxomi.init({portal: 'IHRE PORTAL-ID',
        accessToken: 'AUTHENTIFIZIERUNGS-TOKEN',
        errorHandler : function(obj) {

            // in einem entsprechenden Container ausgeben
            $('#error').text(obj.json.message);


            // mit der Fehlerbehandlungs-Routine jetzt stoppen
            return true;
        },
        failureHandler : function(obj) {

            // in einem entsprechenden Container ausgeben
            $('#error').text(obj.error.message);
        }
});

Interceptor

Mithilfe eines Interceptor ist es möglich in das Verhalten der Integration einzugreifen. Nachdem der JavaScript-Code die OXOMI-Schnittstelle abgefragt hat und bevor das Ergebnis in das HTML integriert wird, kann ein Interceptor-Code eingebunden werden.

Der Interceptor kann zum Beispiel dazu dienen Anpassungen an den abgerufenen Daten aus der Schnittstelle an spezielle Anforderungen anzupassen.

Parameter	Beschreibung
interceptor	Gibt eine JavaScript-Funktion an, die nach dem OXOMI-Aufruf ausgeführt wird. Als Parameter wird hierbei die Ergebnis-Datenstruktur zur Verfügung gestellt. Wird eine Funktion übergeben, welche zwei Parameter entgegen nimmt z.B. `function (json, handler)` so muss die Funktion selbst den `handler` aufrufen und das zu verarbeitende json weitergeben.

Renderer

Der Renderer ist dafür verantwortlich, die eingesetzten Templates mit Daten zu befüllen oder kann dazu verwendet werden, eine völlig eigene Template-Strategie umzusetzen.

Eine individuelle Renderer-Funktion kann zum Beispiel dazu verwendet werden, um OXOMI in eine Single-Page-Anwendung zu integrieren. Anstatt die abgerufenen Daten in einem HTML-Template anzuzeigen, könnte mit einer passenden Renderer-Funktion auch ein "DataTable" oder andere dynamische Widgets befüllt werden.

Benutzen Sie das Property renderer, um eine eigene Renderer-Funktion zu benutzen.

Parameter	Beschreibung
renderer	Gibt eine JavaScript-Funktion an, welche die abgerufenenen Daten auf eine individuelle Weise ausgeben kann. Die Funktion muss folgende Signatur haben: `function (json)`.

Activator

Der Activator ist dafür gedacht nach der Integration des Template-Schnipsels in die umgebende Anwendung neue Eventlistener auf eventuell neue HTML-Elemente zu legen, um diese mit Funktionen der entsprechenden Anwendung zu verbinden.

Parameter	Beschreibung
templateActivator	Gibt eine Funktion an, welche nach Ausführen des Template aufgerufen wird. Diese kann dazu verwendet werden, jQuery-Aktionen auf das generierte HTML zu legen. Die Funktion muss folgende Signatur haben: `function (_target, args, json)`. Hierbei ist _target das jQuery Element des Ziel-Containers. args enthält die Map, mit welcher embedVideo aufgerufen wurde und json enthält die original Antwort des Servers, welche alle relevanten Informationen enthält.

Leere Ergebnisse

Standardmäßig wird die JavaScript-Integration von OXOMI keine Änderung an der Seite vornehmen, wenn keine Ergebnisse für eine artikelbezogene Abfrage gefunden wurden. Wenn Sie in diesem Fall aber anders reagieren möchten (z.B. eine Meldung einblenden) können Sie die folgenden Möglichkeiten verwenden. Grundsätzlich funktioniert dies bei allen artikelbezogenen Funktionen (itemXXXX(...)).

Am einfachsten ist es den target Container standardmäßig ausblenden (style="display:none") und mit einer entsprechenden Meldung vorzubefüllen (z.B. Es wurden leider keine Bilder gefunden.). Anschließend können Sie bei dem entsprechenden Aufruf, z.B. itemImages, den Parameter alwaysShowTarget: true mitgeben. Dadurch wird der Container auch sichtbar gemacht, wenn nichts gefunden wurde - so wird Ihre Meldung eingeblendet.

Alternativ können Sie bei dem Aufruf itemXXX(...) eine Funktion unter dem Name emptyResultHandler mitgeben. Diese wird aufgerufen, wenn der Server keine passenden Daten findet. Als Parameter bekommt diese Funktion eine Map, welche args (alle Aufrufparameter), target (Name des Ziel-Containers) und json (die Serverantwort) enthält.

Weiterhin können Sie eine globale emptyResultHandler Funktion (s.o.) bei oxomi.init definieren, welche bei allen Aufrufen verwendet wird.

Beispiel:

// Behandlung auf globaler Ebene...
oxomi.init({portal: 'IHRE PORTAL-ID',
        accessToken: 'AUTHENTIFIZIERUNGS-TOKEN',
        emptyResultHandler : function(ctx) {
            $(ctx.target).text('Es wurden keine Ergebnisse gefunden');

        }
});

// Behandlung pro Aufruf
oxomi.itemImages({
        supplierNumber: 'L10190',
        itemNumber: 'A20876',
        emptyResultHandler : function(ctx) {
            $(ctx.target).text('Es wurden keine Bilder gefunden');

        }
});

Abschlussfunktion

Mit dem Property completionHandler haben Sie die Möglichkeit eine Funktion zu definieren, mit der Sie zum Abschluss der nochmal eingreifen können.

Beispiel:

oxomi.itemPages({
    supplierNumber: 'L10190',
    itemNumber: 'A20876',
    completionHandler : function(ctx) {
        // Alle OXOMI-Daten besonders hervorheben
        $('[class^=oxomi]').addClass('highlight');
    }
});

Das Javascript Objekt, das der completionHandler Funktion übergeben wird hat immer mindestens 3 Properties: target ist der jQuery Selektor des Ziel-Containers. args enthält das Objekt, womit der OXOMI-Aufruf gestartet wurde, json enthält die Original-Antwort des Servers, welche alle relevanten Informationen zum Aufruf enthält.

Ablaufreihenfolge

Die Ablaufreihenfolge des Codes ist die folgende:

Schritt 1	Schnittstellen-Aufruf
Schritt 2	Fehlerbehandlung
Schritt 3	Interceptor wird aufgerufen
Schritt 4	Renderer wird aufgerufen
Schritt 5	Activator wird aufgerufen
Schritt 6	auxElements-Elemente werden eingeblendet
Schritt 7	classMap-Elemente werden durch entsprechende Klassen ergänzt
Schritt 8	Abschlussfunktion wird aufgerufen, falls vorhanden

Zurück zur Übersicht