Direkt externe Einbindung
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 dasdirect_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 Baumsdeepness={deepness}
(optional) Standard ist 1format={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 3extsid={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 Shopnameextsid={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
Footer / Fusszeile
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 CookiePEPPERSESS=a + extsid=1
) - Synchronisation abgeschlossen.
PEPPERSESS b
wird nicht mehr verwendet und wird entsorgt werden
- Kunde legt Artikel in Warenkorb (
-
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
- Kunde ruft externe Seite auf (
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
- Shop wird mit neuem Browser aufgerufen (erhält
-
Externe Seite wird zuerst aufgerufen
- Kunde ruft externe Seite auf (
PEPPERSESS=a + extsid=1
) + JS/iFrame Call: (PEPPERSESS=a + extsid=1
) - Synchronisation abgeschlossen.
- Kunde ruft externe Seite auf (
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. viaget_hauptnavigation()
indirect_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.
Weitere Hilfe
Benötigen Sie weitere Unterstützung? PepperShop stellt Ihnen unterschiedliche Möglichkeiten zur Verfügung.
- Oft hilft ein Klick in der Administration oben rechts auf das Fragezeichen Icon. Hier erhalten Sie direkt Hilfe zum betroffenen Thema.
- Diverse Antworten finden Sie in den FAQ. Diese sind ebenfalls in der Shopadministration über Hilfe&News -> Hilfearchiv aufrufbar. Oder über unsere Homepage https://www.peppershop.com/de/services/support/faq/
- In der PepperShop Academy https://www.peppershop.com/de/services/academy/ können Sie ganz einfach und bequem diverse kostenlose Video-Anleitungen finden.
- Gerne stehen wir Ihnen auch per Mail oder Telefon zur Verfügung (CHF 195./h) support@glarotech.ch oder +41 71 923 08 58
-
: Siehe auch Modul Design-Connector ↩︎