JavaScript Integration

---

OXOMI kann per JavaScript in Fremdsysteme wie Websites, Shop-Systeme oder ein Intranet eingebunden werden. Sollten Sie Daten direkt von OXOMI abfragen wollen, können Sie unsere  öffentliche API aufrufen. Sollten Sie eine Integration innerhalb einer HTML-Umgebung (Web-Browser) anstreben, so raten wir Ihnen, die im Folgenden beschriebene JavaScript API zu verwenden, da dies wesentlich einfacher ist.

Grundsätzlich kann die Integration immer als Ergänzung durchgeführt werden. Dies bedeutet, dass für einen Integrations-Baustein (siehe unten) ein HTML-Element als Ziel angegeben werden kann (vgl.  jQuery Selektoren). Werden bei OXOMI passende Inhalte gefunden, wird der HTML-Inhalt des Elements geleert und durch den Inhalt von OXOMI ersetzt. Dies ist vor allem dann sinnvoll, wenn eigene Datenbestände mit denen von OXOMI kombiniert werden sollen (Beispielsweise kann dies bei Produktabbildungen eingesetzt werden).

Weiterhin wird das angegebene Element (sowie sein übergeordnetes Element) mittels der jQuery-Funktion $(target).show() sichtbar gemacht. So können sonst leere HTML-Elemente ausgeblendet werden, sollte hierfür kein Inhalt vorhanden sein (Beispielweise bei einer Liste aller aktuellen Aktionen, welche zeitweise leer sein kann). Da wir auch das übergeordnete Element einblenden, kann das Ziel-Element mit einer Überschrift versehen und das ganze zum Beispiel mit einem <div> Element umschlossen werden. So wird auch die Überschrift nur dann eingeblendet, wenn ein passender Inhalt hierfür vorhanden ist.

Einbindung

Hierfür muss der folgende Block am Ende der HTML-Seite (vor </body>) eingebaut werden. Dies sorgt dafür, dass das Laden der Seite nicht verlangsamt wird. Das eingebundene Script kümmert sich nun um alle weiteren Schritte, wie das Laden von jQuery (falls nicht bereits vorhanden) sowie dem Initialisieren eines Basis-Stylesheets (CSS). Somit sehen die integrierten Komponenten modern und gut aus. Natürlich können Sie dies durch eigene CSS-Regeln erweitern.

<script type="text/javascript">
    setTimeout(function() {
        var script = document.createElement("script");
        script.type = "text/javascript";
        script.src = (window.location.protocol == 'https:' ? 'https:' : 'http:') + "//" + (typeof oxomi_server == 'undefined' ? 'oxomi.com' : oxomi_server) + "/assets/frontend/oxomi.js";
        document.getElementsByTagName("head")[0].appendChild(script);
    }, 0);
</script>

Ist die JavaScript-Komponente einsatzbereit, signalisiert diese dies durch das Auslösen des Events oxomi-ready. Zusätzlich ruft die JavaScript-Komponente auch die Funktion mit dem Namen oxomi_ready() auf.

Auf diese Weise ist es möglich nachgelagerte Funktionen zum richtigen Zeitpunkt aufrufen zu lassen. Beispiele finden Sie im nachfolgenden Text.

Initialisierung

Die Initialisierung wird mit der Funktion oxomi.init aufgerufen. Diese kann erst ausgeführt werden, wenn der JavaScript-Komponente vollständig geladen hat.

Um die Funktionsweise der JavaScript-Komponente zu konfigurieren, benutzen Sie die nachfolgenden Parameter als Initialisierungs-Parameter.

Parameter	Beschreibung
portal	Gibt die ID des Portals an, welches angesteuert werden soll.
user	Gibt den Login-Namen des Benutzers an, der Angemeldet werden soll. Wenn Sie OXOMI Profiles verwenden, müssen Sie hier pro Benutzer einen eindeutigen Wert übermitteln. Sollten das Portal öffentlich sein oder Sie nicht zwischen einzelnen Benutzern unterscheiden, so können Sie diesen Parameter weglassen. Weitere Infos finden Sie bei  Authentifizierung .
roles	Gibt eine mit Kommas getrennte Liste von Rollen an, welche dem Benutzer zugeordnet sind. Beispiel: Heizung,Elektro,A-Kunde. Sollten Sie keine Rollen verwenden oder ist das Portal öffentlich, können Sie diesen Parameter weglassen. Weitere Infos finden Sie bei  Authentifizierung .
accessToken	Sollte das Portal nicht öffentlich sein, müssen Sie hier einen Authentifizierungs-Token angeben. Werden die Parameter user oder roles verwendet, so müssen Sie diese bei der Berechnung des Tokens berücksichtigen. Sollte das Portal öffentlich sein, können Sie diesen Parameter weglassen. Weitere Infos finden Sie bei  Authentifizierung .
lang	Nutzen sie diesen Parameter, um die Sprache der Texte, die bei der Webseitenintegration angezeigt wird (wie zb. "Blätterversion"), anzupassen. Fehlt dieser Parameter, wird die in der Verwaltungsoberfläche eingestellte Portalsprache verwendet.
disableOverlayHistory	OXOMI nutzt die Browser History API um Nutzern zu ermöglichen, zwischen Overlays vor und zurück zu springen und um Overlays beim Neuladen einer Seite wiederherzustellen. Falls Sie selbst Teile dieser API nutzen und es dadurch zu Problemen kommt, können Sie jeglichen Zugriff von OXOMI auf die History API abschalten, indem Sie diesen Parameter mit dem Wert true belegen.
lazyLoadSkipInvisible	Wenn Sie unsichtbare OXOMI-Inhalte auf ihrer Seite haben, kann dies in bestimmten Browsern zu Perfomanceproblem mit dem lazyloading von OXOMI-Bildern führen. Wenn Sie diesen Parameter mit dem Wert true belegen, werden dabei unsichtbare Bilder übersprungen. Dies kann jedoch ggf. andere Probleme auslösen. In der Regel sollten sie stattdessen die Integration anpassen, so dass die OXOMI-Inhalte erst geladen wird, sobald sie dem Nutzer angezeigt werden.
debug	Gibt an, ob ausführliche Protokolle in der Browser-Konsole erstellt werden sollen. Dies sollte nur bei der Fehlersuche aktiviert werden.

Die übergebenen Konfigurationswerte werden bei der Initialisierung in einer internen Settings-Variable gespeichert. Auf diese Einstellungen kann dann an anderer Stelle im Code wiederum zugegriffen werden und sind somit Integrationsaufruf-übergreifend.

Auf diese Weise können Sie das Verhalten des Codes durch entsprechende Settings beeinflussen.

Mit Funktionsaufruf oxomi_ready()

Nachdem die JavaScript-Bibliothek und sämtliche Abhängigkeiten erfolgreich geladen wurden, wird eine Funktion namens oxomi_ready() aufgerufen. Hier können Sie die Bibliothek mittels oxomi.init auf Ihr Portal konfigurieren. Anschließend können Sie einzelne Integrations-Komponenten aktivieren (siehe unten).

Fügen Sie hierzu den folgenden Skript-Abschnitt im <head></head> Bereich der HTML-Seite ein:

<script type="text/javascript">
    function oxomi_ready() {
        oxomi.init({portal: 'IHRE PORTAL-ID',
                    user: 'BENUTZERNAME',
                    roles: 'BENUTZERROLLEN',  // in der Regel leer
                    accessToken: 'AUTHENTIFIZIERUNGS-TOKEN'
        });
    }
</script>

Mit oxomi-ready Event

Alternativ können Sie die im Folgenden beschriebenen Integrationsbausteine innerhalb von oxomi_ready aufrufen. Alternativ können Sie, sofern jQuery bereits in der Seite eingebunden ist, entsprechende Callbacks an beliebigen Stellen hinterlegen:

<script type="text/javascript">
    $(document).bind('oxomi-ready', function(e, oxomi) {
        //oxomi....
    });
</script>

Anwendungsfälle

Haben Sie die Integration und Initialisierung in Ihrem System eingebunden, dann können Sie dieses als Basis für weitere Integrationsbausteine nutzen. Diese unterstützen zum Beispiel das Einbinden von Dokumenten, Artikeldaten, Videos und Exposés.

Unsere Anwendungsfälle sind hier im Detail beschrieben:

Einbinden von Dokumenten Einbinden von Videos

Einbinden von Exposés Einbinden artikelbezogener Daten