Dieser Artikel beschäftigt sich mit den Integrationsmöglichkeiten von Stories. Hier steht zum einen die klassische Integration per JavaScript und zum anderen eine serverseitig gerenderte Integration zur Verfügung.
Weitere Informationen zur serverseitigen Einbindung befinden sich im Artikel Public API: Render Stories. Die serverseitige Einbindung ermöglicht eine Suchmaschinen-optimierte (SEO) Integration, da der Inhalt von OXOMI fertig gerendert in Ihre Website eingebunden wird. Dabei ist jedoch zu beachten, dass zusätzlich die clientseitige JavaScript-Integration notwendig ist, um die Interaktivität und die korrekte Darstellung (Styling) der Stories zu gewährleisten.
Die Integration per JavaScript hingegen ist eine einfache Möglichkeit, Stories schnell und effektiv einzubinden. Die nachfolgende ausführliche Beschreibung der JavaScript Integration setzt die im Artikel JavaScript Integrationsgrundlagen beschriebenen Grundlagen voraus. Der Artikel geht dabei insbesondere auf die Parameter (sowie deren Wertebereiche) der vorhandenen Integrationsmöglichkeiten ein und veranschaulicht diese jeweils in einem interaktiven Showcase.
Die Integration oxomi.stories rendert eine Liste von Stories in den angegebenen DOM-Container. Dabei wird je nach gewünschtem Anzeigemodus entweder eine Liste oder ein Slider mit entsprechenden Stories gerendert. Die Integration bietet verschiedene Filter- und Sortiermöglichkeiten mit denen Sie die Ergebnisse einschränken und anpassen können.
Der Aufruf der Integration liefert ein Promise zurück, welches Ihnen die Möglichkeit gibt, entsprechend auf den Abschluss des Aufrufs zu reagieren. Hierfür können Sie die then und catch Methoden des Promise Objekts verwenden. Der nachfolgende JavaScript-Code zeigt ein Beispiel, wie Sie auf den Abschluss des Aufrufs reagieren können.
oxomi.stories({
target: "#output",
displayMode: "list",
showBrandLogos: true,
showDateOfPublication: true
}).then((result) => {
console.log("success");
}).catch((error) => {
console.log("failed");
});
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 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| target | string |
Gibt das Ziel-Element an, in welches die gerenderte Liste von Stories eingefügt wird. Hinweis:
|
||||||||||
| supplierNumbers | string |
Gibt die Lieferantennummern der Partner an, auf welche die Ergebnisse eingeschränkt werden sollen. Hinweis:
|
||||||||||
| excludedSupplierNumbers | string |
Gibt die Lieferantennummern der Partner an, deren Inhalte von den Ergebnissen ausgeschlossen werden sollen. Hinweis:
|
||||||||||
| brandIds | string |
Gibt die IDs der Marken an, auf welche die Ergebnisse eingeschränkt werden sollen. Hinweis:
|
||||||||||
| seriesIds | string |
Gibt die IDs der Serien an, auf welche die Ergebnisse eingeschränkt werden sollen. Hinweis:
|
||||||||||
| tags | string |
Gibt die Tags an, auf welche die Ergebnisse eingeschränkt werden sollen. Hinweis:
|
||||||||||
| categoryIds | string |
Gibt die IDs der Kategorien an, auf welche die Ergebnisse eingeschränkt werden sollen. Hinweis:
|
||||||||||
| types | string |
Gibt die Story-Typen an, auf welche die Ergebnisse eingeschränkt werden sollen. Die verfügbaren Werte können hier eingesehen werden: Story-Typen Hinweis:
|
||||||||||
| sortBy | string |
Gibt die Sortierung der Ergebnisse vor. Die nachfolgenden Werte stehen hier zur Verfügung:
Hinweis:
|
||||||||||
| limit | integer |
Gibt die maximale Anzahl an Stories an, welche innerhalb der Integration angezeigt werden sollen. Hinweis:
|
||||||||||
| own | boolean |
Gibt an, ob nur eigene Stories oder nur Stories von anderen Anbietern angezeigt werden sollen. Hinweis:
|
||||||||||
| showBrandLogos | boolean |
Gibt an, ob die Markenlogos der Stories angezeigt werden sollen. Hinweis:
|
||||||||||
| displayMode | string |
Gibt an, wie die Stories angezeigt werden sollen. Die folgenden Werte stehen zur Verfügung:
Hinweis:
|
||||||||||
| showDateOfPublication | boolean |
Gibt an, ob das Datum der Veröffentlichung der Stories angezeigt werden soll. Hinweis:
|
||||||||||
| filterLanguages | string |
Gibt die Sprachen als 2-buchstabige ISO-Codes an, auf welche die Ergebnisse eingeschränkt werden sollen. Die verfügbaren Werte können hier eingesehen werden: ISO-Sprachcodes Hinweis:
|
||||||||||
| filterCountries | string |
Gibt die Länder als 2-buchstabige ISO-Codes an, auf welche die Ergebnisse eingeschränkt werden sollen. Die verfügbaren Werte können hier eingesehen werden: ISO-Ländercodes Hinweis:
|
Allgemeine Parameter
Aufruf Parameter
Ausgabebereich
Die Integration oxomi.embedStory erlaubt es, eine Story in einen Container einzubetten.
Der Aufruf der Integration liefert ein Promise zurück, welches Ihnen die Möglichkeit gibt, entsprechend auf den Abschluss des Aufrufs zu reagieren. Hierfür können Sie die then und catch Methoden des Promise Objekts verwenden. Der nachfolgende JavaScript-Code zeigt ein Beispiel, wie Sie auf den Abschluss des Aufrufs reagieren können.
oxomi.embedStory({
target: "#output",
story: "7733"
}).then((result) => {
console.log("success");
}).catch((error) => {
console.log("failed");
});
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 |
|---|---|---|
| story | string |
Gibt die ID oder den Code der Story an. Hinweis:
|
| target | string |
Gibt das Ziel-Element an, in welches die gerenderte Story eingefügt wird. Hinweis:
|
| hideShoppingCarts | boolean |
Gibt an, ob die Warenkörbe von möglichen Produktkacheln ausgeblendet werden sollen. Hinweis:
|
Allgemeine Parameter
Aufruf Parameter
Ausgabebereich
Mit der Integration oxomi.openStory kann eine Story in einem Overlay geöffnet werden. So können Sie beispielsweise eine Story aus einer Liste oder aus einem anderen Kontext heraus anzeigen.
Der Aufruf der Integration liefert ein Promise zurück, welches Ihnen die Möglichkeit gibt, entsprechend auf den Abschluss des Aufrufs zu reagieren. Hierfür können Sie die then und catch Methoden des Promise Objekts verwenden. Der nachfolgende JavaScript-Code zeigt ein Beispiel, wie Sie auf den Abschluss des Aufrufs reagieren können.
oxomi.openStory({
story: "7733"
}).then((result) => {
console.log("success");
}).catch((error) => {
console.log("failed");
});
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 |
|---|---|---|
| story | string |
Gibt die ID oder den Code der Story an. Hinweis:
|
| hideShoppingCarts | boolean |
Gibt an, ob die Warenkörbe von möglichen Produktkacheln ausgeblendet werden sollen. Hinweis:
|
Die Integration oxomi.storiesSlider erlaubt es, einen Banner-Slider in einen Container einzubetten. Der Banner-Slider ermöglicht die automatisch durchwechselnde Vorschauanzeige von mehreren Stories in einem Karussell. Die Stories können dabei vom Betrachter mit einem Klick geöffnet werden. Die Anzahl und der Typ der im Slider angezeigten Stories kann dabei konfiguriert werden.
Der Aufruf der Integration liefert ein Promise zurück, welches Ihnen die Möglichkeit gibt, entsprechend auf den Abschluss des Aufrufs zu reagieren. Hierfür können Sie die then und catch Methoden des Promise Objekts verwenden. Der nachfolgende JavaScript-Code zeigt ein Beispiel, wie Sie auf den Abschluss des Aufrufs reagieren können.
oxomi.storiesSlider({
target: "#output",
type: "desktop-slider-slim"
}).then((result) => {
console.log("success");
}).catch((error) => {
console.log("failed");
});
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 | ||||||
|---|---|---|---|---|---|---|---|---|
| target | string |
Gibt das Ziel-Element an, in welches der gerenderte Banner-Slider eingefügt wird. Hinweis:
|
||||||
| type | string |
Gibt den Typ der Stories an, welche im Banner-Slider angezeigt werden sollen. Die nachfolgenden Werte stehen hier zur Verfügung.
|
||||||
| limit | integer |
Gibt die maximale Anzahl an Stories an, welche innerhalb des Banner-Sliders angezeigt werden sollen. Hinweis:
|
Allgemeine Parameter
Aufruf Parameter
Ausgabebereich
OXOMI Stories stellen einige Aktionen bereit, die für einen Button oder ein Bild in der Story hinterlegt werden können. Diese Aktionen werden dann ausgeführt, wenn ein Nutzer auf das entsprechende Element klickt oder tippt. Die folgende Tabelle listet alle verfügbaren Aktionen und deren Effekte auf.
| Code | Link-Aktion | Beschreibung | Verfügbar für Story-Typ |
|---|---|---|---|
| goto | Interner Verweis | Verweist auf ein Segment der Story. | alle |
| catalog | Katalog öffnen | Öffnet einen OXOMI-Katalog in einem Overlay. | alle |
| video | Video öffnen | Öffnet ein OXOMI-Video in einem Overlay. | alle |
| gallery | Exposé öffnen | Öffnet ein OXOMI-Exposé in einem Overlay. | alle |
| story | Story öffnen | Öffnet eine andere OXOMI-Story in einem Overlay. Optional mit Sprungziel innerhalb der Zielstory. | alle |
| product | Produkt-Verweis | Sprungverweis zu einer Produktseite. | alle |
| productsearch | Produktsuche ausführen | Führt im angeschlossenen Shop / Produktdatenbank die vorgegebene Suche aus. | alle |
| expand | Expand (Ausklappen) | Klappt einen eingeklappten Story-Teil aus. | Nur Navlets |
| navpro | Navigator Pro Suche | Setzt vorgegebene Filter in dem aktuell geöffneten Navigator Pro. | Nur Startseiten und Markenwelten für Navigator Pro |
| navpro-all-brands | Alle Marken anzeigen | Öffnet im Navigator Pro die Ansicht aller Marken. | Nur Startseiten und Markenwelten für Navigator Pro |
| navpro-all-metaclasses | Alle Produktgruppen anzeigen | Öffnet im Navigator Pro die Ansicht aller Produktgruppen. | Nur Startseiten und Markenwelten für Navigator Pro |
| navpro-all-productgroups | Alle Hersteller-Produktgruppen anzeigen | Öffnet im Navigator Pro die Ansicht aller Hersteller-Produktgruppen. | Nur Startseiten und Markenwelten für Navigator Pro |
| navpro-all-series | Alle Serien anzeigen | Öffnet im Navigator Pro die Ansicht aller Serien. | Nur Startseiten und Markenwelten für Navigator Pro |
| navpro-all-products | Alle Produkte anzeigen | Öffnet im Navigator Pro die Ansicht aller Produkte. | Nur Startseiten und Markenwelten für Navigator Pro |
Für jede Aktion ist ein Default-Handler definiert, welcher das von OXOMI definierte Standardverhalten ausführt. Wenn Sie allerdings anderweitig auf eine entsprechende Aktion reagiert möchten, kann ein eigener Link-Handler registriert werden. Dies ist vor allem dann notwendig, wenn Produkte aus der Story direkt in Ihrem Webshop gekauft werden sollen.
Im nachfolgenden Abschnitt wird exemplarisch beschrieben, wie ein solcher Handler implementiert und anschließend registriert wird, sodass er vom System aufgerufen werden kann.
Produkt-Verweis und Produktsuche ausführen
Für die Aktionen „Produkt-Verweis“ und „Produktsuche ausführen“ muss jeweils der passende Zielaufruf zwingend selbst implementiert werden. Dazu definieren Sie eine Funktion mit den Parametern link (enthält das URL-Objekt der Story-Aktion) und context (enthält den Aktionstyp, das Aktionsziel und eventuelle URL-Parameter).
Link-Handler für „Produkt-Verweis“ und „Produktsuche ausführen“ könnten beispielsweise so aussehen:
function handleProduct(link, context) {
if (context.action === 'product') {
window.alert('Öffne Produkt "' + context.target + '" mit Lieferantennummer "' + context.supplierNumber + '"');
// Link-Aktion wurde verarbeitet. Weitere Link-Handler für 'product' sollen unterbunden werden.
return true;
}
return false;
}
function handleProductSearch(link, context) {
if (context.action === 'productsearch') {
window.alert('Starte Suche nach Suchbegriff "' + context.target + '"');
// Link-Aktion wurde verarbeitet. Weitere Link-Handler für 'productsearch' sollen unterbunden werden.
return true;
}
return false;
}
Weitere Aktionen
Alle anderen Aktionen werden standardmäßig innerhalb von OXOMI ausgeführt. Sie können jedoch auch durch eigene Link-Handler erweitert oder überschrieben werden. Mit der folgenden Funktion lässt sich beispielsweise ein zusätzlicher Hinweis anzeigen, bevor ein Katalog-Overlay durch die „Katalog öffnen“ Aktion geöffnet wird.
function overwriteOpenCatalog(link, context) {
if (context.action === 'navpro-all-series') {
window.alert('Achtung! Hier wird gleich ein Katalog geöffnet');
}
// Da hier nur ein zusätzlicher Hinweis angezeigt werden soll, werden weitere Link-Handler nicht unterbunden.
return false;
}
Registrierung und Priorität
Das folgende Beispiel zeigt, wie die eigenen Link-Handler bei OXOMI registriert werden. Der Zahlenwert gibt dabei die Ausführungspriorität an, wobei ein Handler mit niedrigerem Wert früher ausgeführt wird. Für die Link-Handler von OXOMI liegt die Priorität immer bei 100. Für eigene Handler muss also ein niedrigerer Wert angegeben werden.
// Je niedriger der Prioritäts-Wert ist, desto früher wird der Link-Handler aufgerufen.
document.addEventListener('oxomi-loaded', function () {
scireum.stories.addLinkHandler(handleProduct, 1);
scireum.stories.addLinkHandler(handleProductSearch, 1);
scireum.stories.addLinkHandler(overwriteOpenCatalog, 1);
});