Story Integration

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.

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 Wertebereich) der vorhandenen Integrationsmöglichkeiten ein und veranschaulicht diese jeweils in einem interaktiven Showcase.

• Story Einbetten
• Banner-Slider
• Story-Aktionen

Diese Integration erlaubt es, eine Story in einen Container einzubetten. Wahlweise können die Warenkörbe der sich innerhalb der Story befindlichen Produktkacheln ein- oder ausgeblendet werden. Um diese Integration nutzen zu können, muss die embedStory Funktion aufgerufen werden. Dies sollte innerhalb eines oxomi-loaded Eventhandlers geschehen, um sicherzustellen, dass die OXOMI JavaScript Bibliothek geladen wurde.

<script type="text/javascript" src="https://oxomi.test.scireum.com/assets/frontend/v2/oxomi.js" async></script>
<script type="text/javascript">
    // Wir warten bis die OXOMI JavaScript Bibliothek geladen ist...
    document.addEventListener('oxomi-loaded', function () {
        oxomi.init({
            // Initialisierung der OXOMI Komponente
        });
        oxomi.embedStory({
            "target": "#container",
            "story": "showcase-embed-story"
        });
    });
</script>

Zur Konfiguration der Integration stehen die nachfolgenden Parameter zur Verfügung. Fett markierte Parameter sind dabei Pflichtparameter. Die restlichen Parameter sind optional und können weggelassen werden.

Diese Integration 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. Um die Banner-Slider Integration nutzen zu können, muss die storiesSlider Funktion aufgerufen werden. Dies sollte innerhalb eines oxomi-loaded Eventhandlers geschehen, um sicherzustellen, dass die OXOMI JavaScript Bibliothek geladen wurde.

<script type="text/javascript" src="https://oxomi.test.scireum.com/assets/frontend/v2/oxomi.js" async></script>
<script type="text/javascript">
    // Wir warten bis die OXOMI JavaScript Bibliothek geladen ist...
    document.addEventListener('oxomi-loaded', function () {
        oxomi.init({
            // Initialisierung der OXOMI Komponente
        });
        oxomi.storiesSlider({
            "target": "#container",
            "type": "desktop-slider-slim"
        });
    });
</script>

Zur Konfiguration der Integration stehen die nachfolgenden Parameter zur Verfügung. Fett markierte Parameter sind dabei Pflichtparameter. Die restlichen Parameter sind optional und können weggelassen werden.

OXOMI Stories stellen einige Aktionen bereit, die für einen Button oder ein Bild in der Story hinterlegt werden können. Die folgende Tabelle listet alle verfügbaren Aktionen und deren Effekte auf.

Product Reference und Product Search Reference

Für die Aktionen „Product Reference“ und „Product Search Reference“ 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 „Product Reference“ und „Product Search Reference“ 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 „Open catalog“ 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);
});