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. 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) sichtbar gemacht. So können ansonsten leere HTML-Elemente ausgeblendet bleiben, sollte hierfür kein Inhalt vorhanden sein – etwa eine Liste aller aktuellen Aktionen, welche zeitweise leer sein kann. Da auch das übergeordnete Element einblendet wird, kann das Ziel-Element beispielsweise mit einer Überschrift versehen und das ganze mit einem vorläufig versteckten <div> Element umschlossen werden. So wird auch die Überschrift nur dann eingeblendet, wenn passender Inhalt vorhanden ist.
Um Sie bei der Integration zu unterstützen, haben wir einige Beispiele erstellt. Es stehen zwei CodePen-Collections bereit: Die erste beinhaltet einfachere Beispiele und wird insbesondere in der Knowledgebase verwendet. Die zweite enthält allgemeine, häufig angewandte Szenarien.
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 beispielsweise das Initialisieren eines Basis-Stylesheets (CSS). Natürlich können Sie dies durch eigene CSS-Regeln erweitern.
<script type="text/javascript" src="https://oxomi.com/assets/frontend/v2/oxomi.js" async></script>
Ist die JavaScript-Komponente einsatzbereit, signalisiert diese dies durch das Auslösen des Javascript-Events oxomi-loaded.
<script type="text/javascript">
document.addEventListener('oxomi-loaded', function () {
// Initialisierung...
});
</script>
Auf diese Weise ist es möglich die Initialisierung zum richtigen Zeitpunkt ausführen zu lassen. Ein Beispiel finden Sie im nachfolgenden Text.
Die Initialisierung wird mit der Funktion oxomi.init aufgerufen. Diese kann erst ausgeführt werden, wenn die JavaScript-Komponente vollständig geladen ist. Dies wird signalisiert durch das Auslösen des Javascript-Events oxomi-loaded.
<script type="text/javascript">
document.addEventListener('oxomi-loaded', function () {
oxomi.init({
portal: 'DemoPortal',
user: 'DemoUser',
accessToken: '85ce97869dd565fa4d5ad1aec7a81c1a',
...
});
});
</script>
Sobald die Initialisierung abgeschlossen ist, wird das Javascript-Event oxomi-configured ausgelöst. Dieses Event kann genutzt werden, um die einzelnen Integrationen aufzurufen.
<script type="text/javascript">
document.addEventListener('oxomi-configured', function () {
oxomi.universalSearch({
...
});
// Weitere Funktionsaufrufe...
});
</script>
Zur Konfiguration der JavaScript-Komponente bietet Ihnen die Funktion oxomi.init verschiedene Parameter an.
Die nachfolgende Tabelle enthält eine Übersicht über die verfügbaren Parameter. Fett gedruckte Parameter sind Pflichtparameter. Die Beschreibung der Parameter enthält Informationen über den Typ des Parameters, die möglichen Werte und die Bedeutung sowie weitere Verwendungshinweise.
| Parameter | Parametertyp | Beschreibung |
|---|---|---|
| portal | string |
Gibt die ID des Portals an, in dessen Kontext die anschließenden OXOMI-Aufrufe stattfinden sollen. Das Portal gibt insbesondere vor, welche Inhalte grundsätzlich zur Verfügung stehen. |
| user | string |
Gibt den Login-Namen des Benutzers an, der angemeldet werden soll. Hinweis:
|
| roles | string |
Gibt eine mit Kommas getrennte Liste von Rollen an, welche dem Benutzer zugeordnet sind. Hinweis:
|
| accessToken | string |
Sollte das Portal nicht öffentlich sein, müssen Sie hier einen Authentifizierungs-Token angeben. Hinweis:
|
| language | string |
Nutzen Sie diesen Parameter, um die Sprache der Texte anzupassen, die bei der Webseitenintegration verwendet wird (wie etwa „Blätterversion“). Die Sprachen werden als 2-buchstabige ISO-Codes angegeben. Die verfügbaren Werte können hier eingesehen werden: ISO-Sprachcodes Hinweis:
|
| disableOverlayHistory | boolean |
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. Hinweis:
|
| lazyLoadSkipInvisible | boolean |
Wenn Sie unsichtbare OXOMI-Inhalte auf ihrer Seite haben, kann dies in bestimmten Browsern zu Perfomanceproblem mit dem Lazy-Loading (Nachladen von Inhalten erst bei Notwendigkeit) von OXOMI-Bildern führen. Hinweis:
|
| debug | boolean |
Gibt an, ob ausführliche Protokolle in der Browser-Konsole erstellt werden sollen. Hinweis:
|
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.