Individualisierung mit Custom Widgets
- Sebastian Meyer
Vorsicht! Hier wird es sehr technisch - die Erstellung und Nutzung von Custom Widgets erfordert Programmierkenntnisse und Fehler in der Umsetzung können deinen Shop zeitweise unerreichbar werden lassen. Lasse dir hier also gegebenenfalls von einem Servicepartner unter die Arme greifen.
Aufgrund der Natur der Komplexität von Custom Widgets können wir auch keinen Support für Custom Widgets anbieten.
PS: Wir empfehlen grundsätzlich - aber insbesondere auch für die Entwicklung von Custom Widgets - die Verwendung einer Testumgebung!
Einleitung
Custom Widgets sind spezielle Widgets, die nur für einen einzelnen Händler entwickelt sind und somit nicht Kernbestandteil des Plugins und Template sind. Imgrunde so etwas wie Plugins für das easyTemplate360.
Custom Widgets bestehen im Wesentlichen aus 3 Teilen:
Eine JSON-Datei, die die Datenstruktur und Darstellung im Plugin (im Shop-Adminbereich) steuert.
Eine PHP-Datei, die das Mapping der im Plugin konfigurierten Einstellungen in Smarty-Variablen steuert.
Eine Template-Datei, die die Smarty-Variablen / Einstellungen für das Frontend rendert.
Um den Start in die Custom Widget-Entwicklung zu erleichtern, gibt es für jede dieser Dateien auch Beispiele im easyTemplate360 Parent-Template.
Eine Warnung vorweg: Auch wenn es theoretisch auch anders funktionieren kann, sollten Custom Widgets immer nur als Bestandteil von Child-Templates ausgeliefert werden.
JSON-Datei (Datenstrukturen und Metadaten)
Ablageort: MeinChild/config/custom_widgets/
Diese Datei definiert den technischen Type des Custom Widgets, sowie die Einstellungen (IDs, Typen, Beschriftungen).
Die Basis-Struktur sollte dabei wie folgt aussehen:
Beispiel.json
{
"_comment": "Ein interner Kommentar - wird nirgends ausgegeben.",
"description": {
"de": "Dieser Beschreibungtext wird im Plugin-Backend ausgegeben und kann auch <b>HTML</b> enthalten.",
"en": "This description text is displayed in the plugin backend and may contain <b>HTML</b>."
},
"type": "Beispiel",
"label": {
"de": "Beispiel Custom Widget",
"en": "Example Custom Widget"
},
"version": "1.0.0",
"areas": [
"all"
],
"settings": [
- deine Settings hier -
]
}Essentiell ist der Type, da dieser auch steuert, welche PHP-Klasse angesprochen wird, wenn das Widget gerendert wird.
Um einen Überblick über die Settings zu bekommen, die du nutzen kannst, wirf einen Blick in die easyTemplate360/config/custom_widgets/Example.json.
Hinweis: Du solltest Namenskollisionen mit existierenden Widget-Typen vermeiden. Am besten erreicht man das durch einen geeigneten Vendor-Prefix.
PHP-Datei (Mapping der Konfiguration)
Ablageort: MeinChild/src/CustomWidgets
Wichtig 1: Die PHP-Datei zu einem CustomWidget, welches den Type “Beispiel” definiert, muss CustomWidgetBeispiel heißen, sonst funktioniert das Autoloading und das Matching zu den Widget-Daten nicht.
Wichtig 2: Die PHP-Klasse muss im Namespace Template\easytemplate360\src\CustomWidgets definiert werden, unabhängig davon, wie die eigentliche Ordner-Struktur aussieht.
Wichtig 3: Du musst die PHP-Klasse auch noch laden. Das kannst du in der Bootstrap.php deines Child-Templates erreichen, indem du in der boot()-Methode folgendes aufrufst:
$this->registerCustomWidgetClassFile(__DIR__ . '/src/CustomWidgets/CustomWidgetBeispiel.php');Die PHP-Datei steuert im Wesentlichen, wie die Einstellungen des Händlers im Plugin-Backend auf Smarty-Variablen gemappt werden sollen.
Die Basis-Struktur sollte dabei wie folgt aussehen:
CustomWidgetBeispiel.php
<?php declare(strict_types=1);
namespace Template\easytemplate360\src\CustomWidgets;
class CustomWidgetBeispiel extends BaseCustomWidget
{
/**
* @inheritDoc
*/
protected function prepareSmarty(): void
{
/*
Deine Mappings / Befüllung von $this->smartyConfig aus $this->config.
In $this->config, einem assoziativen Array, steht dir die "rohe" Konfiguration aus dem
Plugin-Backend zur Verfügung.
$this->smartyConfig ist ein assoziativer Array und steht dir in deiner Template-Datei
als Smarty-Variable $et_Beispiel zur Verfügung.
*/
}
}
Damit du nicht das Rad neu erfinden musst, gibt es für die komplexeren Datentypen diverse Methoden mit dem Namen $this->resolve*, welche deine PHP-Klasse aus BaseCustomWidget erbt.
Um einen Überblick über die resolve*-Methoden zu bekommen, wirf einen Blick in die easyTemplate360/src/CustomWidgets/CustomWidgetExample.php.
Template-Datei (Rendering der gemappten Daten)
Ablageort: MeinChild/custom_widgets
Wichtig: Der Name der Template-Datei wird automatisch bestimmt, indem der Type des CustomWidgets von PascalCase nach snake_case konvertiert wird. Also DasIstMeinBeispiel würde die Template-Datei das_ist_mein_beispiel.tpl erwarten.
Zu guter Letzt brauchst du im Normalfall auch noch eine Template-Datei, die die Daten, die du dir gemappt hast auch im Template ausgibt.
Diese Datei kannst du im Prinzip beliebig strukturieren. Wenn du aber wie ein reguläres Widget (in einem Container) gerendert werden möchtest, kannst du widgets/base/widget.tpl extenden und eine Beispiel-Datei würde so aussehen:
beispiel.tpl