Direkt externe Einbindung

Benötigte Lesezeit: 9 Minuten


Einleitung

Mit dem Direkt-Extern Modul kann man auf externen Webseiten einzelne Komponenten direkt aus dem Shop auslesen und anzeigen. So ist es zum Beispiel möglich, Artikel, ganze Artikellisten oder auch den Warenkorb auf einer Webseite anzuzeigen. Oft wird auch der Kategorienbaum des Shops ausgelesen, um z.B. in einer CMS Designintegration1 im responsive Teil für das Mobile-Menü zu verwenden.

Aktuell bestehen folgende Möglichkeiten der Anbindung:

  • Kategorien
  • Kategorienbaum
  • Einzelartikel
  • Mehrere Artikel, optional gefiltert
  • Shop-Header
  • Hauptnavigation
  • Footer (Fusszeile)
  • Komponenten (Login, Suche, Warenkorb, JavaScript-Elemente, Session-Load/Sync)

Installation

Systemanforderungen

Um das Direkt-Extern Modul einzusetzen, ist mindestens ein PepperShop v.5.0 Professional erforderlich. Es empfiehlt sich ein möglichst aktueller Build.

Dateien kopieren und hochladen

Das Direkt-Extern Modul kann nach dem Bezug im Download Bereich des eigenen PepperShop Accounts heruntergeladen werden. Es besteht aus zwei Verzeichnissen, die man in seinen installierten PepperShop kopieren muss. Dazu entpackt man zuerst das ZIP-Archiv. Es sind folgende Dateien enthalten, die hier mit den Zielverzeichnissen dargestellt werden:

{shopdir}/shop/direct_extern.def.php
{shopdir}/shop/direct_extern_einzelartikel.def.php
{shopdir}/shop/direct_extern_kategorie.def.php
{shopdir}/shop/direct_extern_component.def.php
{shopdir}/shop/direct_extern_login.php
{shopdir}/shop/language/html_templates/direct_extern_einzelartikel.tpl.html
{shopdir}/shop/language/html_templates/direct_extern_kategorie.tpl.html
{shopdir}/shop/language/html_templates/direct_extern_kategorie_special.tpl.html
{shopdir}/shop/language/html_templates/directextern_kategorien.tpl.html
{shopdir}/shop/language/html_templates/directextern_kategorien_xml.tpl.html
{shopdir}/shop/language/html_templates/directextern_multi_artikel.tpl.html
{shopdir}/shop/language/html_templates/direct_extern_component.tpl.html

Die Dateien lassen sich einfach via FTP zum Webserver hochladen. Der Platzhalter {shopdir} steht dabei für das Webshop-Verzeichnis auf dem Webserver, wo unter anderem die Datei index.php zusammen mit README.txt zu finden ist.

Beschreibung

Die Shop-Komponenten werden über eine definierte Webadresse aus dem Shop ausgelesen. Der Aufbau der Adresse ist immer gleich:

Aufruf-URL: http://.../shop/direct_extern.def.php?op={op}&{zusatzparameter}

Der Parameter op definiert, welche Ausgabe gemacht wird. Mit den Zusatzparametern können dazu noch weitere Einstellungen übergeben werden. Nun folgt eine detaillierte Auflistung der möglichen Aufrufe und deren Parameter. Je nach Projekt werden nur einige der vorhandenen Parameter eingesetzt.

Es wird empfohlen, dass die Ausgaben der Aufrufe jeweils per AJAX geladen werden, womit auch die Session-Zuordnung automatisiert funktioniert. Das standardmässig verwendete Format der Informationen ist JSON. In Kapitel 3 wird ein einfaches Beispiel hierzu gezeigt.

Anwendungsbeispiel externe Webseite

Als praktisches Beispiel wird davon ausgegangen, dass zu einer Webseite ein Shop angebunden wird. Damit die Integration möglichst transparent für den Kunden wirkt, soll das Design der Webseite in den Shop übernommen werden. Dabei soll der Warenkorb und die Suche auf der Webseite integriert werden.

Aufrufe im CMS

Damit diese Komponenten im CMS angezeigt werden können, sind folgende Operationen notwendig:

  • Komponenten: op=shc
  • Kategorien: op=skb&format=json

Mit den Komponenten werden das Login, die Suche, der Warenkorb, das Javascript und (falls als Modul installiert) die Merkliste eingebunden.

Der Aufruf für die Kategorien ist notwendig, damit der Kategorienbaum des Shops im Mobile-Menü der Webseite erweitert wird.

Per AJAX kann der Kategorienbaum ausgelesen werden und das JSON direkt dem Mobile-Menü hinzugefügt werden, wenn die Shop-Kategorien darin enthalten sein sollen. Dasselbe gilt für die Komponenten, natürlich an entsprechend passender Stelle eingefügt.

API / Aufrufe

Nachfolgend werden die einzelnen Möglichkeiten aufgelistet und die Parameter, welche für die Anwendungen notwendig sind, beschrieben.

Komponenten (Login, Suche, Warenkorb, JavaScript, Session-Load, (Merkliste))

Einzelne Shop-Komponenten werden in einen Aufruf exportiert. Die Komponenten sind in einem JSON-Array mit direktem HTML-Code gelistet:

  • session-load
  • login
  • quicksearch
  • warenkorb
  • javascript
  • merkliste (falls Modul installiert)

Anmerkungen:

Für die Suchfunktion (Quicksearch) muss noch das Javascript und das jquery-ui.css CSS eingebunden werden.

Aufruf

  • http://.../shop/direct_extern.def.php?op=shc&{zusatzparameter}

Zusatzparameter

  • extsid={Externe Session-ID} (optional)
  • für empfohlenen AJAX-Aufruf werden keine Parameter benötigt

Template

Folgende Template-Dateien werden verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu den Dateien lautet: {shop_dir}/shop/language/html_templates/

  • login: kundenaccount.tpl.html
  • quicksearch: quicksearch.tpl.html
  • warenkorb: warenkorb_kurzinfo.tpl.html

Suche: Direkte Quicksearch Suchanfrage

Verwenden Sie die Schnellsuche des PepperShop Systems, um deren Resultate in Ihre CMS-Suchresultate einzubinden (Info: Diese Abfrage steht erst ab PepperShop v.6.0.0 Build 32 bereit):

Aufruf

http://.../shop/ajax_handler.php?
ajax_handler_id=artikelsuche_search_name
&feldname=Suchstring
&alt_label=Name
&deeplinks=true
&only-article=false
&image=true
&sprachwahl={sprachwahl}
&term={Suchtext}

Zusatzparameter

  • term = Ihr Suchstring (urlencodiert)
  • sprachwahl = Optionale Angabe der Sprache (de, en, fr, it, ..)
  • only-article = true | false: Nur Artikel oder auch Kategorien?
  • image = true | false: Links zu Bildern ausgeben?

Template

Es wird direkt JSON Code retourniert, bei einem Fehler wird eine Fehlermeldung retourniert.
Beispiel Rückmeldung (Info: value steht für die interne Shop Artikel-/Kategorie-ID):

[
  {
    "value": "14",
    "label": "Pfeffer",
    "category": "Kategorien",
    "deeplink": "http://demo.peppershop.com/ki.php/pfeffer.html"
  },
  {
    "value": "67",
    "label": "PepperShop Pfefferschote",
    "category": "Artikel",
    "image": "http://demo.peppershop.com/shop/ProdukteBilder/67_kl.jpg",
    "deeplink": "http://demo.peppershop.com/pi.php/PepperShop-Pfefferschote.html"
  },
  {
    "value": "66",
    "label": "Wo der Pfeffer w\u00e4chst (Taschenbuch)",
    "category": "Artikel",
    "image": "http://demo.peppershop.com/shop/ProdukteBilder/pfeffer002_kl.jpg",
    "deeplink": "http://demo.peppershop.com/pi.php/Wo-der-Pfeffer-waechst-Taschenbuch.html"
  },
  {
    "value": "65",
    "label": "Teufelsk\u00fcche. H\u00f6llisch scharfe Sachen. (Taschenbuch)",
    "category": "Artikel",
    "image": "http://demo.peppershop.com/shop/ProdukteBilder/65_kl.jpg",
    "deeplink": "http://demo.peppershop.com/pi.php/Teufelskueche-Hoellisch-scharfe-Sachen-Taschenbuch.html"
  }
]

Kategorien

Es wird der HTML-Code für eine bestimmte Kategorie und deren Artikel exportiert.

Es gibt hier jeweils einen Darstellungstyp (‘normal’ oder ‘special’):

  • normal: Die Kategorie rendert in einer Schleife die Artikel, welche ebenfalls im normal-Modus gerendert werden (einstufig, ohne Blättern)
  • special: Hier wird das direct_extern_kategorie_special.tpl.html angewendet, welches direkt zur Artikel Renderingfunktion durchgereicht wird, das heisst, dass man in einem Template die Anpassung aller Darstellungsoptionen für die Kategorie und deren Artikel übernimmt, dies ermöglicht speziellere Darstellungen.

Aufruf

  • http://.../shop/direct_extern.def.php?op=sk1&{zusatzparameter}

Zusatzparameter

  • entweder: Kategorie_Nr={Kategorie_Nr}
  • oder: Kategorie_ID={Kategorie_ID}

Template

Folgende Template-Dateien werden verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu den Dateien lautet: {shop_dir}/shop/language/html_templates/

  • Darstellungstyp normal: direct_extern_kategorie.tpl.html
  • Darstellungstyp special: direct_extern_kategorie_special.tpl.html

Artikelfilter

Falls nicht alle Artikel dieser Kategorie angezeigt werden sollen, kann man beliebig viele Filterregeln auf die Daten eines Aritkelobjekts anwenden. Dazu wird ein Filterarray mit enthaltenen Filterregeln in direct_extern.def.php erzeugt und bei der Instanzierung des jeweiligen Objekts dem Konstruktor mit übergeben.

Eine Filterregel besteht aus einem Array mit drei Elementen (assoziativ):

  • membervar: Name der Membervariable des jeweiligen Artikelobjekts (z.B. artikel­_Nr, Zusatzfeld_5, …)
  • operation: Eine Vergleichsoperation mit zwei Operanden, z.B. <, >, <=, >=, ==
  • operand: Verglichener Wert - meist ein vorgegebener Wert
    Beispiel:

    $filter = array(
    array(
        'membervar' => 'Zusatzfeld_1',
        'operation' => '==',
        'operand'   => 'V',
        'special'   => 'ignore_case'
    )
    );

Kategorienbaum

Der HTML-Code oder JSON-Code für den Kategorienbaum wird exportiert.

Aufruf

  • http://.../shop/direct_extern.def.php?op=skb&{zusatzparameter}

Zusatzparameter

  • Kategorie_Nr={Kategorie_Nr} (optional) Standard ist 0, ganzer Baums
  • deepness={deepness} (optional) Standard ist 1
  • format={format} (optional) Standard ist html
    • mögliche Werte: html, xml, json
  • extsid={Externe-Session-ID} (optional)

Template

  • Darstellungstyp html: directextern_kategorien.tpl.html
  • Darstellungstyp xml: directextern_kategorien_xml.tpl.html
  • Darstellungstyp json: Hat kein Template.

Beispiel JSON-Format:

{
  "category-entry": [
    {
      "name": "Pfeffer",
      "class": "kat_inaktiv",
      "href": "SHOPDIR/ki.php/Pfeffer-14.html"
    },
    {
      "name": "DVD",
      "class": "kat_inaktiv",
      "href": "SHOPDIR/ki.php/DVD-13.html"
    },
    {
      "name": "Pizzeria",
      "class": "kat_inaktiv",
      "href": "SHOPDIR/ki.php/Pizzeria-18.html",
      "categories": {
        "category-entry": [
          {
            "name": "Pizza",
            "class": "kat_inaktiv",
            "href": "SHOPDIR/ki.php/Pizza-19.html"
          },
          {
            "name": "Spezial-Pizza",
            "class": "kat_inaktiv",
            "href": "SHOPDIR/ki.php/Spezial-Pizza-20.html"
          }
        ]
      }
    }
  ]
}

Einzelartikel

Der HTML-Code für einen einzelnen Artikel wird exportiert.

Einschränkungen:

  • keine Mindestbestellmenge berücksichtigt
  • keine Staffelpreise
  • keine Standard PepperShop Variationen
  • keine Standard PepperShop Zusatztexte
  • keine Subartikel
  • keine Cross-Selling Anzeige (manuell + automatisch)
  • keine Artikelzusatzfelder
  • keine Artikel mit Preis gleich 0.00

Aufruf

  • http://.../shop/direct_extern.def.php?op=sa&{zusatzparameter}

Zusatzparameter

  • Artikel_Nr={Artikel_Nr}
  • Kategorie_Nr={Kategorie_Nr} (optional)
  • extsid={Externe Session-ID} (optional)

Template

Folgende Template-Datei wird verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu der Datei lautet: {shop_dir}/shop/language/html_templates/

  • direct_extern_einzelartikel.tpl.html

Mehrere Artikel

Der HTML-Code für eine Artikelliste wird exportiert. Es wird maximal die Anzahl Produkte aufgelistet und bei Promo diese prioritär. Die Ausgabe wird während 1 Stunde zwischengespeichert.

Aufruf

  • http://.../shop/direct_extern.def.php?op=sma&{zusatzparameter}

Zusatzparameter

  • Kategorie_Nr={Kategorie_Nr}
  • anzahl={anzahl} (optional) Standard ist 3
  • extsid={Externe Session-ID} (optional)

Template

Folgende Template-Datei wird verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu der Datei lautet: {shop_dir}/shop/language/html_templates/

  • directextern_multi_artikel.tpl.html

Shop-Header

Der HEAD-Bereich des Shops wird als HTML exportiert.

Aufruf

  • http://.../shop/direct_extern.def.php?op=shh&{zusatzparameter}

Zusatzparameter

  • title={Seitentitel} Standard Shopname
  • extsid={Externe Session-ID} (optional)

Template

Folgende Template-Datei wird verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu der Datei lautet: {shop_dir}/shop/language/html_templates/

  • hauptseite.tpl.html

Hauptnavigation

Die ganze Hauptnavigation wird als HTML exportiert.

Aufruf

  • http://.../shop/direct_extern.def.php?op=shn&{zusatzparameter}

Zusatzparameter

  • extsid={Externe Session-ID} (optional)

Template

Folgende Template-Dateien werden verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu den Dateien lautet: {shop_dir}/shop/language/html_templates/

  • direct_extern_component.tpl.html
  • hauptnavigation.tpl.html

Der Footer wird als HTML exportiert.

Aufruf

  • http://.../shop/direct_extern.def.php?op=sf&{zusatzparameter}

Zusatzparameter

  • extsid={Externe Session-ID} (optional)

Template
Folgende Template-Dateien werden verwendet um die Ausgabe zu rendern / formatieren. Der Pfad bis zu den Dateien lautet: {shop_dir}/shop/language/html_templates/

  • direct_extern_component.tpl.html
  • footer.tpl.html

Session

Info: Wird die Integration von Komponenten via empfohlenem AJAX-Aufruf getätigt, kann dieses Kapitel übersprungen werden.

Das Session-Management unterstützt die Zuordnung einer externen Session-ID (extsid) zu einer internen Session. Wenn man den Shop also ohne Session-Cookie mit nur ?extsid=xyz aufruft und diese externe Session-ID ist zuvor an eine existierende Session gebunden worden, so erhält man dieselbe Session wieder. Umgekehrt wird bei der Erstellung einer neuen Session ebenfalls die externe Session-ID direkt verknüpft. Eine externe Session-ID kann immer nur einer einzigen PepperShop Session(-ID) zugewiesen werden

Abläufe:

Externe Ressource ist innerhalb des Shop-Verzeichnisses (PEPPERSESS Cookie ist sichtbar für externe Ressource)

Shop wird zuerst aufgerufen

  • Shop wird mit neuem Browser aufgerufen (erhält PEPPERSESS=a)

    • Kunde legt Artikel in Warenkorb (PEPPERSESS=a)
    • Kunde wechselt zu externer Seite (PEPPERSESS=b + extsid=1) + JS/iFrame Call: (op=s: Via Cookie PEPPERSESS=a + extsid=1)
    • Synchronisation abgeschlossen. PEPPERSESS b wird nicht mehr verwendet und wird entsorgt werden

  • Externe Seite wird zuerst aufgerufen

    • Kunde ruft externe Seite auf (PEPPERSESS=a + extsid=1) + JS/iFrame Call: (PEPPERSESS=b + extsid=1)
    • Synchronisation abgeschlossen. PEPPERSESS b wird nicht mehr verwendet und wird entsorgt werden

Externe Ressource ist ausserhalb des Shop-Verzeichnisses (PEPPERSESS Cookie ist nicht sichtbar für externe Ressource!)

  • Shop wird zuerst aufgerufen

    • Shop wird mit neuem Browser aufgerufen (erhält PEPPERSESS=a)
    • Kunde legt Artikel in Warenkorb (PEPPERSESS=a)
    • Kunde wechselt zu externer Seite (PEPPERSESS=b + extsid=1) + JS/iFrame Call: (op=s: “Magic” PEPPERSESS=a + extsid=1)
    • Synchronisation abgeschlossen. PEPPERSESS b wird nicht mehr verwendet und wird entsorgt werden

  • Externe Seite wird zuerst aufgerufen

    • Kunde ruft externe Seite auf (PEPPERSESS=a + extsid=1) + JS/iFrame Call: (PEPPERSESS=a + extsid=1)
    • Synchronisation abgeschlossen.

Bitte beachten:

  • Beim ersten Aufruf der externen Ressource ist die Synchronisation noch nicht ausgeführt und folglich wird der Warenkorbinhalt noch nicht korrekt angezeigt. Mögliche Lösung: Warenkorb dynamisch nachladen (warenkorb_kurzinfo.def.php, z.B. via get_hauptnavigation() in direct_extern_component.def.php)
  • Externe Ressourcen werden nicht gecached (Session-Sync Calls gibts nur einmal – first call)

Aufruf

  • http://.../shop/direct_extern.def.php?op=s&{zusatzparameter}

Zusatzparameter

  • extsid={Externe Session-ID} (optional)

Template
Keine sichtbare Ausgabe, nur Server-to-Server Kommunikation.

Anhang

Beispielscript für Webseite

Das folgende Beispiel PHP-Skript zeigt die Aufrufe und Anwendung einer typischen Integration von Shop-Komponenten in eine bestehende Webseite per AJAX.

Es werden per Aufruf (http://.../shop/direct_extern.def.php?op=shc) die Komponenten im JSON-Format geladen und danach in den Container mit der ID „results” eingeordnet.

Testweise empfiehlt es sich, im entsprechenden Shop einen Artikel in den Warenkorb zu legen, sich als Kunde einzuloggen oder einen gültigen Suchbegriff abzusetzen.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CMS Vorlage</title>

    <!-- Bootstrap core CSS -->
    <link
      rel="stylesheet"
      href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css"
    />
    <script src="//code.jquery.com/jquery-1.11.3.min.js"></script>
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>
    <link
      rel="stylesheet"
      href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"
    />
    <style>
      .navbar {
        border-radius: 0;
        border-bottom: 4px solid #555555;
        color: #ffffff;
      }
      .navbar-header .navbar-brand {
        padding-top: 15px;
      }
      .footer {
        border-top: 1px #dddddd solid;
        margin-top: 20px;
      }
    </style>
  </head>
  <body>
    <nav class="navbar navbar-inverse">
      <div class="container">
        <div class="navbar-header">
          <button
            type="button"
            class="navbar-toggle collapsed"
            data-toggle="collapse"
            data-target="#navbar"
            aria-expanded="false"
            aria-controls="navbar"
          >
            <span class="sr-only">Toggle navigation</span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>
          <a class="navbar-brand" href="#">Webseite</a>
        </div>
        <div id="navbar" class="collapse navbar-collapse">
          <ul class="nav navbar-nav">
            <li class="active"><a href="#">Home</a></li>
            <li><a href="#">Menu 1</a></li>
            <li><a href="#">Menu 2</a></li>
            <li><a href="#">Webshop</a></li>
          </ul>
        </div>
        <!--/.nav-collapse -->
      </div>
    </nav>

    <div class="container">
      Hier Inhalt CMS<br />
      Ajax-Load:<br />
      <script>
        $.ajax({
          url:
            "<?php echo $shop_verzeichnis.'shop/direct_extern.def.php?op=shc';?>",
          cache: false,
        }).done(function(json_code) {
          var json_obj = jQuery.parseJSON(json_code);
          $('#results').append(json_obj.warenkorb);
          $('#results').append(json_obj.login);
          $('#results').append(json_obj.javascript); // Fuer Quicksearch
          $('#results').append(json_obj.quicksearch);
        });
      </script>
      <div id="results"></div>
    </div>
    <!-- Site footer -->
    <div class="container">
      <footer class="footer">
        <p>Footer</p>
      </footer>
    </div>
  </body>
</html>

Aufruf von anderer Domain

Wenn obiger Beispiel-Aufruf auf einer unterschiedlichen Domain durchgeführt wird, kommt die CORS Restriktion zum Einsatz. Fügen Sie in diesem Fall folgenden Code in die .htaccess-Datei auf dem Server ein, wo der PepperShop installiert ist:

Header set Access-Control-Allow-Origin "http://example.com"
#damit Cookies uebertragen werden können
Header set Access-Control-Allow-Credentials true

Die „ANFRAGENDE DOMAIN” ist entsprechend der Server bzw. die URL gemeint, woher der AJAX-Aufruf abgesetzt wird.

🌶️
🔥
🌶️