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.

Hinweis: Damit OXOMI-Integrationen ohne Probleme funktionieren, wird ein aktueller Browser vorrausgesetzt. Von OXOMI unterstützt werden:

  • Aktuelle Versionen von Google Chrome, Mozilla Firefox und Microsoft Edge
  • Mircosoft Internet Explorer 11 und 10 (auf Microsoft Windows)
  • Apple Safari 9 und neuer (auf macOS / Mac OS X)

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.

Hinweis: Falls JQuery auf Ihrer Seite schon vorhanden ist, stellen Sie sicher dass Sie eine aktuelle Version benutzen, damit die OXOMI-Integration funktionieren kann:

  • Eine aktuelle JQuery 1 Version: 1.10.2 (wird von OXOMI verwendet) oder neuer
  • Eine aktuelle JQuery 2 Version: 2.2.4 oder neuer
  • Eine aktuelle JQuery 3 Version: 3.1.1 oder neuer

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.

forceHTML5

Wird dieser Parameter mit dem Wert true belegt, werden Dokumente im neuem HTML5-Viewer geöffnet.

forceFlash

Wird dieser Parameter mit dem Wert true belegt, werden Dokumente im Flash-Viewer geöffnet, wenn Flash im Browser aktiviert ist.

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