Die info.xml
Im Root-Verzeichnis jedes Plugins liegt die XML-Datei info.xml
.
In dieser Datei sind alle Informationen zum Plugin hinterlegt.
Die Datei beinhaltet neben dem Namen des Plugins, der Beschreibung und dem Autor auch alle technischen Informationen. Darunter fallen z. B. Pfade zu Ressourcen, verwendete Hooks, Sprachvariablen, Einstellungselemente und mehr.
Hint
Diese Datei ist das wichtigste Element eines Plugins, da sie für die Installation sowie für Updates zuständig ist.
Ein Plugin kann in folgende Hauptbestandteile aufgeteilt werden, die durch die info.xml
definiert werden:
- Globale Plugin-Informationen
- Versionen
- Adminmenü mit Custom-Links und Setting-Links
- Zahlungsmethoden
- Frontend-Links
- Sprachvariablen
- E-Mail-Templates
- Plugin-Boxen
- Plugin-Lizenzierung
- statische Ressourcen
Falls Bereiche im Plugin nicht gebraucht werden, sollten Sie den kompletten Block weggelassen. Die globalen Informationen können dabei nicht weggelassen werden.
Der Rumpf
Das Hauptelement stellt den Rumpf der XML-Datei dar. Es heißt <jtlshopplugin>
.
Ab JTL-Shop 5.x:
<jtlshopplugin>
...
</jtlshopplugin>
Globale Plugin-Informationen
Nach dem Rumpf der XML-Datei folgen allgemeine Informationen, die als Kindelemente angehängt werden.
<jtlshop3plugin>
<Name></Name>
<Description></Description>
<Author></Author>
<URL></URL>
<XMLVersion></XMLVersion>
<ShopVersion></ShopVersion>
<PluginID></PluginID>
</jtlshop3plugin>
Elementname | Funktion |
---|---|
<Name> * |
Name des Plugins ([a-zA-Z0-9_] ) |
<Description> |
Plugin-Beschreibung |
<Author> |
Herausgeber eines Plugins |
<URL> |
Link zum Pluginherausgeber |
<XMLVersion> * |
Version der info.xml ([0-9]{3} ) |
<ShopVersion> |
synonym für MinShopVersion |
<MinShopVersion> |
Mindestversion von JTL-Shop 5 |
<MaxShopVersion> |
Maximalversion von JTL-Shop 5 |
<PluginID> * |
Plugin-Identifikator ([a-zA-Z0-9_] ) |
<Icon> |
Dateiname zu einem Icon |
<Version> |
die Plugin-Version ([0-9]+ ) |
<CreateDate> |
Erstellungsdatum (YYYY-MM-DD) |
<ExsID> |
ExtensionStore-ID |
(*)Pflichtfelder
Name
Der Name des Plugins wird in der Plugin-Verwaltung und den automatisch generierten Menüs im Backend dargestellt. Er dient der Identifizierung des Plugins.
Description
Die Beschreibung wird in der Plugin-Verwaltung im Tab "Verfügbar" unterhalb des Plugin-Namens dargestellt. Sie enthält eine kurze Funktionsbeschreibung des Plugins.
Author
Der Autor wird im Admin-Menü des Plugins dargestellt. Hier kann sowohl eine Firma als auch eine Privatperson eingetragen werden.
URL
Die URL sollte einen Link zum Hersteller oder einer dedizierten Plugin-Seite enthalten, sodass der Kunde schnell und einfach weitere Informationen oder Support erhalten kann.
XMLVersion
Da sich mit der Zeit auch die Anforderungen an das Plugin-System ändern können, kann sich auch die XML-Installationsdatei ändern. Daher ist die Angabe der XML-Version sehr wichtig, um auch die richtigen Parameter für das eigene Plugin zur Verfügung zu haben.
ShopVersion
Ab JTL-Shop 5.0.0 ist dieser Tag ein Synonym für
MinShopVersion
MinShopVersion entspricht ab Shop 5.0.0 dem alten Tag ShopVersion.
MaxShopVersion
MaxShopVersion gibt die Version von JTL-Shop an, die höchstens unterstützt wird. Ist die tatsächlich installierte Version von JTL-Shop höher, wird im Backend eine Warnung angezeigt.
Shop4Version
Ab JTL-Shop 5.0.0 wird dieser Tag nicht mehr unterstützt!
Plugin-ID
Die Plugin-ID identifiziert ein Plugin im Onlineshop eindeutig.
Vergeben Sie unbedingt eine sinnvolle und einmalige ID für das eigene Plugin, damit
gleichnamige Plugins unterschiedlicher Hersteller nicht kollidieren.
Beispiel-ID für ein Plugin: "SoftwareFirma_PluginName"
Namenskonvention:
Es sind nur die Zeichen a-z
bzw. A-Z
, 0-9
und der Unterstrich erlaubt.
Punkt und Bindestrich sind nicht erlaubt.
Ab JTL-Shop 5.0.0 entspricht die Plugin-ID außerdem dem automatisch zugewiesenen PSR-4 Namespace
(angeführt vom Präfix Plugin\
) für das gesamte Plugin.
Achten Sie deshalb darauf, dass der Ordnername des Plugins der Plugin-ID entspricht. Ein Plugin mit der
Plugin-ID "mycompany_someplugin" erhält so den Namespace Plugin\mycompany_someplugin
.
Icon
Aktuell noch nicht implementiert, perspektivisch zur besseren Übersicht geplant.
Version
Ab JTL-Shop 5.x ist dies eine Pflichtangabe zur Definition der Pluginversion.
CreateDate
Ab JTL-Shop 5.x ist dies eine Pflichtangabe zur Definition des Erstellungsdatums der jeweiligen Pluginversion.
Das Datum muss im Format YYYY-MM-DD
angegeben werden, beispielsweise "2019-03-21" für den 21. März 2019.
ExsID
Die ExsID
muss für alle Plugins ab JTL-Shop 5.0.0 angegeben werden, wenn das Plugin im JTL-Store vertrieben werden
soll.
Sie finden die ExsID
im Kundencenter, nachdem Sie dort eine Extension für den Marktplatz angelegt haben.
Install-Block
Nach den globalen Plugininformationen folgt der Installationsblock. Dieser sieht wie folgt aus:
<Install>
</Install>
Alle Informationen zum Plugin werden in diesem Block als Kindelemente aufgeführt.
Versionierung
Wie die zur Definition passende Verzeichnisstruktur aussieht, finden Sie unter "Aufbau" im Abschnitt "Versionierung".
Ab JTL-Shop 5.x
Es befindet sich in der info.xml
lediglich die wesentlich vereinfachtere Struktur:
<jtlshopplugin>
...
<CreateDate>2018-11-13</CreateDate>
<Version>1.0.0</Version>
...
</jtlshopplugin>
Plugin-Hooks
Nach der Versionierung folgt das <Hooks>
-Element. In diesem Element werden jene Stellen im Onlineshop definiert,
an denen das Plugin Code ausführen soll.
Der Frontend-Link und die Zahlungsmethoden benötigen keine expliziten Hookangaben, da diese an einem bestimmten Hook vom System aus eingebunden werden.
Beispiel:
<Hooks>
<Hook id="129">onlineuser.php</Hook>
<Hook id="130">managemenet.php</Hook>
</Hooks>
Die ID identifiziert hierbei eindeutig eine bestimmte Stelle im Code von JTL-Shop. Die angegebene PHP-Datei wird dann am Hook der ID ausgeführt. Möchten Sie z. B. nach dem Erstellen eines Artikelobjektes am Objekt noch einige Member verändern, so können Sie den entsprechenden Hook benutzen, um dies zu erledigen.
Elementname | Funktion |
---|---|
<id> * |
Eindeutige Hook-ID ([0-9]+ ) |
<priority> |
Priorität (niedriger => frühere Ausführung) ([0-9]+ ) |
<Hook> |
PHP-Datei im Ordner frontend/ , die an ID ausgeführt wird |
(*) Pflichtfelder
Werden keine Hooks vom Plugin benötigt, können Sie den gesamten Hook-Container weglassen.
Eine Liste der Hook-IDs finden Sie in der "Hook-Liste". Weitere Informationen zum Hook-System des Onlineshops finden Sie im Kapitel "Hooks".
Ab JTL-Shop 5.x existiert eine neue Alternative zu den bekannten Hooks in JTL-Shop - der EventDispatcher. Wie Sie Gebrauch von diesem neuen Feature machen, finden Sie im Kapitel "Bootstrapping" unter "Der EventDispatcher".
Lizenzierung
Bei der Erstellung kommerzieller Plugins für JTL-Shop stellt sich die Frage, wie das eigene Plugin gegen unautorisierte Weitergabe und Nutzung abgesichert werden kann.
Ein Plugin kann dem Onlineshop via info.xml
mitteilen, dass es unter einer bestimmten Lizenz steht und diese
abgefragt werden muss.
Für diesen Zweck stellt der Onlineshop eine Interface-Klasse zur Verfügung, die das Plugin nutzen kann, um eine
bestimmte Lizenzmethode zu überschreiben. Diese Methode wird dann beim Aufruf des Plugins stets überprüft.
Wie und mit welchen Mitteln das Plugin seine Lizenz überprüft, muss selbst implementiert werden. Am Ende der Methode muss dem System nur mitgeteilt werden, ob die Prüfung erfolgreich war oder fehlschlug.
Um dem Onlineshop mitzuteilen, dass eine Lizenzprüfung benötigt wird, fügen Sie folgende Elemente in die info.xml
ein:
<LicenceClass>PluginLicence</LicenceClass>
<LicenceClassFile>PluginLicence.php</LicenceClassFile>
Elementname | Beschreibung |
---|---|
<LicenceClass> |
Lizenzprüfungsklasse des Plugins, die von der Interface-Klasse PluginLizenz des Onlineshops erbt |
<LicenceClassFile> |
Dateinamen der Lizenzprüfungsklasse des Plugins |
(*) Pflichtfeld
Wo Sie die benötigten Dateien ablegen können, erfahren Sie im Kapitel "Aufbau" im Abschnitt "Lizenzierung".
Ab JTL-Shop 5.x
In JTL-Shops der Versionen 5.x ist die Methodik der Interface-Vorschrift verglichen mit den Vorgängerversionen gleich geblieben. Allerdings ist hier die Unterstützung von namespaces hinzugekommen.
Beispiel:
<?xml version='1.0' encoding="UTF-8"?>
<jtlshopplugin>
<Name>SimpleExample</Name>
<Description>Ein einfaches Bespiel</Description>
<Author>JTL-Software-GmbH</Author>
<URL>https://www.jtl-software.de</URL>
<XMLVersion>102</XMLVersion>
<ShopVersion>500</ShopVersion>
<PluginID>jtl_demo_plugin</PluginID>
<Version>1.0.0</Version>
<CreateDate>2019-02-26</CreateDate>
<LicenceClass>PluginLicence</LicenceClass>
<LicenceClassFile>PluginLicence.php</LicenceClassFile>
<Install>
...
</Install>
</jtlshopplugin>
Die entsprechende Lizenzprüfungsklasse mit namespace würde dann so aussehen:
<?php
namespace Plugin\[PluginID]\licence;
use JTL\Plugin\LicenseInterface;
class PluginLicence implements LicenseInterface
{
/**
+ @param string $cLicence
+ @return mixed
*/
public function checkLicence($cLicence)
{
// ...
return (bool)$isValid;
}
}
Weiterhin bietet es sich an, die Pluginlizenzklasse mit Hilfe von "ionCube" zu verschlüsseln, um Manipulationen vorzubeugen.
Important
JTL-Shop selbst benötigt seit Version 4.00 kein Ioncube mehr. Es ist also nicht garantiert, dass potentielle Käufer tatsächlich bereits Ioncube auf ihrem Server installiert haben.
Frontend-Ressourcen
Pluginentwickler haben über die XML-Tags <CSS>
und <JS>
die Möglichkeit, eigene Ressourcen
im Plugin mitzuliefern, die im Frontend auf allen Seiten eingebunden werden.
Dies hat den Vorteil, dass sie nicht einzeln über das Template bzw. via pq()
("phpQuery") eingebunden werden
müssen. Darüber hinaus können sie auch direkt minifiziert werden.
<Install>
...
<CSS>
<file>
<name>foo.css</name>
<priority>4</priority>
</file>
<file>
<name>bar.css</name>
<priority>9</priority>
</file>
</CSS>
<JS>
<file>
<name>foo.js</name>
<priority>8</priority>
<position>body</position>
</file>
<file>
<name>bar.js</name>
</file>
</JS>
</Install>
CSS-Datei:
Elementname | Beschreibung |
---|---|
<name> * |
Der Dateiname im Unterordner css/ (siehe auch: Aufbau) |
<priority> |
Die Priorität von 0-10, je höher, desto später wird die Datei eingebunden |
JS-Datei:
Elementname | Beschreibung |
---|---|
<name> * |
Der Dateiname im Unterordner js/ (siehe auch: Aufbau) |
<priority> |
Die Priorität von 0-10, je höher, desto später wird die Datei eingebunden |
<position> |
Die Position im DOM, an der die Datei eingebunden wird, "body" oder "head" |
(*) Pflichtfeld
Alle hier angegebenen Dateien müssen im Unterordner frontend/css/
bzw. frontend/js/
liegen.
Eine Beispieldarstellung finden Sie im Abschnitt "Aufbau" unter "Frontend-Ressourcen".
JavaScript-Dateien lassen sich dabei über das Attribut "position" wahlweise in den Header oder Body einfügen.
Sie können über "priority" (0 = höchste, 5 = Standard) in der Reihenfolge modifiziert werden.
Falls zu einer über diese Methode eingebundenen CSS-Datei ein _custom.css
-Pendant im selben Ordner existiert,
wird dieses zusätzlich nach der eigentlichen CSS-Datei eingebunden.
Dem obigen Beispiel folgend wären dies foo_custom.css
bzw. bar_custom.css
.
Attention
Für JavaScript-Dateien wird dieses Vorgehen nicht unterstützt.
Minify
Diese Dateien werden, bei entsprechend aktivierter Theme-Funktion, auch minifiziert.
Im Theme müssen dazu die Smarty-Variablen $cPluginJsHeadd_arr
, $cPluginCss_arr
und $cPluginJsBody_arr
geprüft bzw. ausgegeben werden.
Beispiel:
{*
mit aktiviertem minify, header.tpl
*}
{if isset($cPluginCss_arr) && $cPluginCss_arr|@count > 0}
<link type="text/css" href="{$PFAD_MINIFY}/g=plugin_css" rel="stylesheet" media="screen" />
{/if}
{if isset($cPluginJsHead_arr) && $cPluginJsHead_arr|@count > 0}
<script type="text/javascript" src="{$PFAD_MINIFY}/g=plugin_js_head"></script>
{/if}
{*
footer.tpl:
*}
{if isset($cPluginJsHead_arr) && $cPluginJsHead_arr|@count > 0}
<script type="text/javascript" src="{$PFAD_MINIFY}/g=plugin_js_body"></script>
{/if}
{*
ohne minify, header.tpl
*}
{foreach from=$cJS_arr item="cJS"}
<script type="text/javascript" src="{$cJS}"></script>
{/foreach}
{if isset($cPluginJsHead_arr)}
{foreach from=$cPluginJsHead_arr item="cJS"}
<script type="text/javascript" src="{$cJS}"></script>
{/foreach}
{/if}
{*
footer.tpl
*}
{if isset($cPluginJsHead_arr)}
{foreach from=$cPluginJsBody_arr item="cJS"}
<script type="text/javascript" src="{$cJS}"></script>
{/foreach}
{/if}
Objektcache
Sollen bei der Installation des Plugins bestimmte Inhalte des Objektcaches gelöscht werden, weil das Plugin
beispielsweise Artikeldaten modifizieren soll, so kann im Element <FlushTags>
eine Liste von Tags angegeben
werden, welche die einzelnen Zwischenspeicher repräsentieren, die zum Zeitpunkt der Installation zurückgesetzt werden
sollen.
<FlushTags>CACHING_GROUP_CATEGORY, CACHING_GROUP_ARTICLE</FlushTags>
Weitere Informationen zum Caching und den vorhandenen Tags finden Sie im Kapitel "Cache".
Boxen
Mit der Boxenverwaltung von JTL-Shop kann der Onlineshopbetreiber einfach und schnell Boxen im Onlineshop verschieben, anlegen oder löschen.
Ein Plugin ist ebenfalls in der Lage, einen neuen Boxentyp anzulegen. Wo die Templates für diese Boxen im Plugin zu platzieren sind, finden Sie unter "Aufbau", im Abschnitt "Boxen". Diese neue Box kann in der Boxenverwaltung ausgewählt und einer Stelle in JTL-Shop zugewiesen werden. Der Inhalt dieser Box wird durch ein Template, das der Box zugewiesen ist, gesteuert. Dort können beliebige Inhalte angezeigt werden.
Sie erstellen einen neuen Boxentyp, indem Sie folgenden neuen XML-Knoten in der info.xml
anlegen:
<Install>
...
<Boxes>
...
</Boxes>
...
</Install>
Innerhalb dieses Knotens können dann beliebig viele Unterelemente vom Typ <Box>
liegen.
Das heißt, ein Plugin kann beliebig viele Boxentypen anlegen.
Vergeben Sie stets eindeutige Boxennamen, damit sich diese nicht mit anderen Plugins überschneiden.
Beispiel:
<Boxes>
<Box>
<Name>ExampleBoxFromExamplePlugin</Name>
<Available>0</Available>
<TemplateFile>example_box.tpl</TemplateFile>
</Box>
</Boxes>
Elementname | Beschreibung |
---|---|
<Name> |
Name des Boxentyps |
<Available> |
Seitentyp, in dem die Box angezeigt wird |
(z. B.: 0= jede Seite, 1= Artikeldetails, 2= Artikelliste, usw.) | |
<TemplateFile> |
Templatedatei mit dem Inhalt der Box |
Soll beispielsweise eine Box auf der Artikeldetailseite und in der Artikelliste des EVO-Templates angezeigt werden,
würden Sie diese Box in der info.xml
zweimal definieren - für jeden dieser Seitentypen:
<Boxes>
<Box>
<Name>MyBox 1</Name>
<Available>1</Available>
<TemplateFile>box_1.tpl</TemplateFile>
</Box>
<Box>
<Name>MyBox 1</Name>
<Available>2</Available>
<TemplateFile>box_1.tpl</TemplateFile>
</Box>
</Boxes>
Available
gibt dabei den Seitentyp an, auf dem die Box dargestellt werden soll. Die entsprechenden Seitentypen
finden Sie in der includes/defines_inc.php
.
Widgets
Mit Plugin-Widgets lassen sich einfach und schnell eigene Widgets im Backend-Dashboard von JTL-Shop implementieren.
Ein Plugin ist in der Lage, ein AdminWidget anzulegen. Der Inhalt dieses Widgets wird durch eine Klasse und ein Template gesteuert. Somit können beliebige Inhalte angezeigt werden. Wo die zugehörigen Dateien zu platzieren sind, erfahren Sie unter "Aufbau" im Abschnitt "Widgets".
Sie erstellen einen neues AdminWidget, indem Sie folgenden neuen XML-Knoten im XML-Container <Install>
in Ihrer info.xml
einfügen:
<Install>
...
<AdminWidget>
...
</AdminWidget>
...
</Install>
In diesem XML-Container können sich beliebig viele Unterelemente vom Typ <Widget>
befinden.
Das heißt, ein Plugin kann beliebig viele AdminWidgets anlegen.
Beispiel:
<AdminWidget>
<Widget>
<Title>Serverinfo (Plugin)</Title>
<Class>Info</Class>
<Container>center</Container>
<Description>Beispielplugin</Description>
<Pos>1</Pos>
<Expanded>1</Expanded>
<Active>1</Active>
</Widget>
</AdminWidget>
Elementname | Beschreibung |
---|---|
<Title> * |
Titelüberschrift des AdminWidgets |
<Class> * |
Klassenname der PHP-Klasse, die den Inhalt des Widgets bereitstellt |
<Container> * |
Position des Dashboardcontainers. Werte: center, left, right |
<Description> |
Beschreibung des AdminWidgets |
<Pos> * |
Vertikale Position im Container. Ganzzahl (1 = oben) |
<Expanded> * |
AdminWidget soll ausgeklappt oder minimiert sein. Ganzzahl, 0 oder 1. |
<Active> * |
AdminWidget direkt sichtbar im Dashboard. Ganzzahl, 0 oder 1. |
(*) Pflichtfeld
Widgets ab JTL-Shop 5.x
Ab JTL-Shop 5.0.0 werden Klassen wie folgt generiert:
- Annahme: Das XML schreibt vor, die Klasse heißt
<Class>Info</Class>
und die Plugin-ID lautet<PluginID>jtl_test</PluginID>
. - Dann muss im Verzeichnis
/adminmenu/widget/
des Plugins die DateiInfo.php
liegen (siehe auch: Abschnitt "Aufbau / Widgets") - Die Klasse in der Datei muss den Namen "Info" tragen und von der Basisklasse "AbstractWidget" abgeleitet sein.
- Die Klasse muss im Namespace
<PluginID>
liegen.
Beispiel:
<?php
namespace jtl_test;
use JTL\Widgets\AbstractWidget;
class Info extends AbstractWidget
{
}
Portlets (ab 5.0.0)
Ab Shop 5.0.0 können Plugins auch Portlets für den OnPageComposer definieren.
Dies geschieht über den XML-Knoten <Portlets>
, der seinerseits unlimitiert viele Unterknoten vom Typ <Portlet>
enthalten kann.
<Install>
...
<Portlets>
<Portlet>
<Title>MyTitle</Title>
<Class>MyClass</Class>
<Group>content</Group>
<Active>1</Active>
</Portlet>
<Portlet>
<Title>MyOtherTitle</Title>
<Class>MyOtherClass</Class>
<Group>content</Group>
<Active>1</Active>
</Portlet>
</Portlets>
...
</Install>
<Portlet>
:
Elementname | Beschreibung |
---|---|
<Title> * |
Titel des Portlets (lokalisierbar mit PO-Datei), wie im "OPC-Editor" (Frontend) und unter "OnPage Composer" im Backend angezeigt |
<Class> * |
Klassenname des Portlets |
<Group> * |
Name der Gruppe, unter welcher das Portlet in der Portlet-Palette eingeordnet ist |
<Active> * |
Status (1 = aktiviert, 0 = deaktiviert) |
(*) Pflichtfeld
Portlets bestehen immer aus einer PHP-Datei mit dem Dateinamen <Portlet-Class-Name>.php
, die eine einzelne Klasse
mit dem Namen <Portlet-Class-Name>
definiert und sich im
Namespace Plugin\[Plugin-ID]\Portlets\[Portlet-Class-Name]
befinden muss.
Diese neue Portletklasse sollte immer von der OPC-Portlet-Klasse JTL\OPC\Portlet
des Onlineshops erben.
Beispiel:
<?php declare(strict_types=1);
namespace Plugin\jtl_test\Portlets;
use JTL\OPC\Portlet;
class MyPortlet extends Portlet
{
// ...
}
Die korrekte Platzierung aller entsprechenden Dateien in Ihrem Plugin finden Sie unter "Aufbau" im Abschnitt "Portlets (ab JTL-Shop 5.0.0)". Wie Sie mit Ihren neuen Portlets weiter verfahren können, lesen Sie im Abschnitt Portlets.
Blueprints (ab 5.0.0)
Ab JTL-Shop 5.0.0 können Plugins auch Blueprints, also Kompositionen von einzelnen Portlets, definieren.
Hierfür definiert man ebenfalls wieder einen neuen Knoten namens Blueprints
im Container Install
, der
seinerseits wiederum unlimitiert Unterknoten des Typs Blueprint
enthalten kann.
<Install>
...
<Blueprints>
<Blueprint>
<Name>Bild links Text rechts</Name>
<JSONFile>image_4_text_8.json</JSONFile>
</Blueprint>
<Blueprint>
<Name>Text links Bild rechts</Name>
<JSONFile>text_8_image_4.json</JSONFile>
</Blueprint>
</Blueprints>
...
</Install>
Blueprint:
Elementname | Beschreibung |
---|---|
<Name> * |
Der im OPC Control Center angezeigte Name |
<JSONFile> * |
Name der JSON-Datei im Unterordner blueprints/ des Plugins |
(*) Pflichtfeld
Erstellt werden können die json-Datein über den Export im OPC-Editor. Wie diese Struktur unterhalb Ihres Plugins aussieht, finden Sie unter "Aufbau" im Abschnitt "Blueprints (ab JTL-Shop 5.0.0)".
Portlet Input-Typen (ab 5.3.0)
Benutzerdefinierte Portlet-Eigenschaften können über den Knoten PortletInputTypes
definiert werden:
<jtlshopplugin>
...
<Install>
...
<PortletInputTypes>
<PortletInputType>
<Name>my-input-type</Name>
</PortletInputType>
...
</PortletInputTypes>
</Install>
...
</jtlshopplugin>
Weitere Information finden Sie auf der Seite Portlets.
Consent-Manager (ab 5.0.0)
Ab JTL-Shop 5.0.0 können Plugins eigene Einträge im Consent-Manager definieren.
Um das zu realisieren, fügen Sie den XML-Knoten <ServicesRequiringConsent>
in die info.xml
Ihres Plugins
ein. Dieser XML-Knoten kann selbst wiederum beliebig viele Unterknoten des Typs <Vendor>
beinhalten.
Beispiel:
<Install>
...
<ServicesRequiringConsent>
<Vendor>
<ID>myItemID</ID>
<Company>Meine kleine Firma GmbH</Company>
<Localization iso="GER">
<Name>Name meines Eintrags</Name>
<Purpose>Tut etwas Tollen</Purpose>
<Description>Dies ist die Beschreibung einer Funktionalität, welche Consent erfordert.
</Description>
<PrivacyPolicy>https://www.example.com/privacy?hl=de</PrivacyPolicy>
</Localization>
<Localization iso="ENG">
<Name>Name of my item</Name>
<Purpose>Does something great</Purpose>
<Description>This is a longer description.
</Description>
<PrivacyPolicy>https://www.example.com/privacy</PrivacyPolicy>
</Localization>
</Vendor>
</ServicesRequiringConsent>
...
</Install>
<Vendor>
:
Elementname | Beschreibung |
---|---|
<ID> * |
ID des Elements ([a-zA-Z0-9_] ) |
<Company> * |
Firmenname |
<Localization> * |
Gruppe von Übersetzungen |
<Localization>
:
Elementname | Beschreibung |
---|---|
<Name> * |
Name der Funktionalität |
<Purpose> * |
Zweck des Cookies |
<Description> * |
Ausführliche Beschreibung des Zweckes und der Funktionalität |
<PrivacyPolicy> * |
Externer Link zur Datenschutzerklärung |
(*) Pflichtfeld
Adminmenü
Im Administrationsbereich von JTL-Shop werden im Menüpunkt Pluginverwaltung alle Plugins angezeigt, die entweder
nicht installiert (verfügbar), fehlerhaft oder installiert sind.
Falls kein Adminmenü gewünscht ist, lassen Sie bitte den kompletten <Adminmenu>
-Container weg.
Fehlerhafte Plugins werden mit dem entsprechenden Fehlercode angezeigt. Eine Tabelle mit möglichen Fehlercodes finden Sie unter Fehlercodes.
<Adminmenu>
...
</Adminmenu>
In diesem Element folgen, je nach Bedarf, das Kindelement <Customlink>
("Custom-Links") und
<Settinglink>
("Setting-Links").
Falls kein <Customlink>
und kein <Settinglink>
existiert, wird der <Adminmenu>
-Container ignoriert.
Custom-Links
Custom-Links werden im Adminbereich unter dem jeweiligen Plugin angezeigt. Mit Hilfe dieser Links kann ein Plugin Seiten mit eigenem Inhalt im Backend anlegen, die Informationen für den Betreiber des Onlineshops bereitstellen. Custom-Links werden im Backend in Tabs dargestellt.
<Customlink sort="1">
<Name>Statistik</Name>
<Filename>stats.php</Filename>
</Customlink>
Elementname | Funktion |
---|---|
Attribut sort= * |
Sortierungsnummer des Tabs |
<Name> * |
Name des Tabs ([a-zA-Z0-9_\-]+ ) |
<Filename> * |
Ausführbare PHP-Datei |
(*)Pflichtfelder
Setting-Links
Setting-Links sind Tabs, die Einstellungen zum Plugin abfragen. Hier können beliebig viele Einstellungen angelegt werden. Einstellungen können unterschiedliche Werte abfragen (z. B Text, Zahl, Auswahl aus einer Selectbox). Diese Einstellungen können durch den Betreiber des Onlineshops im Backend konfiguriert und dann im eigenen Plugin-Code abgefragt werden.
<Settingslink sort="2">
<Name>Einstellungen</Name>
<Setting type="text" initialValue="Y" sort="4" conf="N">
<Name>Online Watcher</Name>
<Description>Online Watcher</Description>
<ValueName>onlinewatcher</ValueName>
</Setting>
</Settingslink>
<Settinglink>
:
Elementname | Funktion |
---|---|
Attribut sort= * |
Sortierungsnummer des Tabs |
<Name> * |
Name des Tabs |
<Setting> * |
Einstellungselement |
(*)Pflichtfelder
<Setting>
:
Elementname | Funktion |
---|---|
Attribut type= * |
Einstellungstyp (text , textarea , selectbox , checkbox , radio , |
colorpicker , email , date , time , tel , url [ab Shop 5.0: none ]) |
|
Attribut initialValue= * |
Vorausgewählte Einstellung |
Attribut sort= |
Sortierung der Einstellung (höher = weiter unten) |
Attribut conf= * |
Y = echte Einstellung, N = Überschrift |
Attribut multiple= * |
Mehrfachauswahl für type = selectbox, Y = Ja, N = Nein |
<Name> * |
Name der Einstellung ([a-zA-Z0-9_\-]+ ) |
<Description> |
Beschreibung der Einstellung |
<ValueName> * |
Name der Einstellungsvariable, die im PHP-Code genutzt wird |
<SelectboxOptions> |
Optionales Kindelement bei type = selectbox |
<RadioOptions> |
Optionales Kindelement bei type = radio |
<OptionsSource> |
Dynamische Quelle für Optionen in Checkbox/Selectbox |
(*)Pflichtfelder
Ab JTL-Shop 5.0.0 kann als Typ auch "type=none
" gewählt werden. Solche Optionen werden nicht im Settings-Tab
angezeigt.
Dies bietet sich an, falls eine eigene Darstellung in einem anderen Tab für die Option gewählt werden soll.
Der Wert wird dann trotzdem in der Plugininstanz gespeichert, sodass kein Umweg über eine eigene SQL-Logik
erforderlich ist. Allerdings müssen Sie den Objektcache ggf. manuell invalidieren.
Falls der Typ der Einstellung type=selectbox
ist, geben Sie das Kindelement <SelectboxOptions>
an.
<SelectboxOptions>
<Option value="Y" sort="1">Ja</Option>
<Option value="N" sort="2">Nein</Option>
</SelectboxOptions>
Elementname | Funktion |
---|---|
<Option> * |
Angezeigter Wert in der Selectbox-Option |
Attribut value= * |
Wert der Selectbox-Option |
Attribut sort= |
Sortierung der Option (höher = weiter unten) |
(*)Pflichtfelder
Falls der Typ der Einstellung type=radio
ist, geben Sie das Kindelement <RadioOptions>
an.
<RadioOptions>
<Option value="Y" sort="1">Ja</Option>
<Option value="N" sort="2">Nein</Option>
<Option value="V" sort="3">Vielleicht</Option>
</RadioOptions>
Elementname | Funktion |
---|---|
<Option> * |
Angezeigter Wert in der Radio-Option |
Attribut value= * |
Wert der Radio-Option |
Attribut sort= |
Sortierung der Option (höher = weiter unten) |
(*)Pflichtfelder
Anstelle von oder zusätzlich zu RadioOptions bzw. SelectboxOptions können Sie das
Element <OptionsSource>
hinzufügen. Sobald es vorhanden ist, wird das RadioOptions- bzw. SelectboxOptions-Element
ignoriert.
Elementname | Funktion |
---|---|
<File> * |
Dateiname, relativ zu adminmenu |
(*)Pflichtfelder
Hierdurch können in einer PHP-Datei dynamische Optionswerte definiert werden. Dies ist insbesondere dann sinnvoll, wenn keine statischen Auswahlmöglichkeiten wie "Ja/Nein" o. Ä. zur Auswahl angeboten werden sollten, sondern z. B. Artikel/Kategorien/Seiten oder andere onlineshopspezifische Werte. Die angegebene Datei muss ein Array von Objekten liefern, wobei als Objektmember jeweils "cWert" und "cName" und optional "nSort" vorhanden sein müssen.
Die entsprechende Datei muss sich hierbei im Ordner adminmenu/
des Plugins befinden.
(siehe auch: Abschnitt "adminmenu/" Struktur)
Beispiel für eine dynamische Option:
<?php
$options = [];
$option = new stdClass();
$option->cWert = 123;
$option->cName = 'Wert A';
$option->nSort = 1;
$options[] = $option;
$option = new stdClass();
$option->cWert = 456;
$option->cName = 'Wert B';
$option->nSort = 2;
$options[] = $option;
$option = new stdClass();
$option->cWert = 789;
$option->cName = 'Wert C';
$option->nSort = 2;
$options[] = $option;
return $options;
In diesem Beispiel würden entsprechend die 3 Auswahlmöglichkeiten "Wert A", "Wert B" und "Wert C" zur Auswahl stehen.
Übersetzung von Settings
Ab JTL-Shop 5.0.0 können Plugin-Optionen mehrsprachig gestaltet werden.
Dies betrifft in jedem <Setting>
-Element die Knoten <Name>
und <Description>
sowie die Werte von
<SelectboxOptions>
und <RadioOptions>
.
Die jeweiligen Werte können als msgid-Schlüssel in der base.po
des Plugins angegeben und übersetzt werden.
Generell müssen Sie hierzu im Unterordner locale/
des Plugins für jede zu übersetzende Sprache einen Unterordner
mit zugehörigem IETF-Language-Tag und darin die Datei base.po
erstellen.
Die entsprechende Verzeichnisstruktur finden Sie unter "Aufbau"
im Abschnitt "Mehrsprachige Settings (ab 5.0.0)".
Beispiel:
Angenommen, Sie möchten die folgende Option in die Sprachen Englisch und Deutsch übersetzen:
<Setting type="selectbox" initialValue="Y" sort="1" conf="Y">
<Name>Finden Sie das hier hilfreich?</Name>
<Description>Stellt eine simple Ja/Nein-Frage</Description>
<ValueName>myplugin_is_helpful</ValueName>
<SelectboxOptions>
<Option value="Y" sort="0">Ja</Option>
<Option value="N" sort="1">Nein</Option>
<Option value="V" sort="2">Vielleicht</Option>
</SelectboxOptions>
</Setting>
Im Beispiel wollen Sie eine einfache "Ja/Nein"-Frage in den Settings unseres Plugins stellen.
Legen Sie folgende Dateien unter der Plugin-Root an:
locale/de-DE/base.po
locale/en-US/base.po
Ausführliche Informationen dazu finden Sie im Kapitel "Aufbau" im Abschnitt "Mehrsprachige Settings (ab 5.0.0)".
Der Inhalt könnte für Deutsch folgendermaßen aussehen (de-DE/base.po
):
msgid "Ja"
msgstr "Ja"
msgid "Nein"
msgstr "Nein"
msgid "Finden Sie das hier hilfreich?"
msgstr "Finden Sie das hier hilfreich?"
msgid "Stellt eine simple Ja/Nein-Frage"
msgstr "Stellt eine simple Ja/Nein-Frage"
und für Englisch entsprechend so (en-US/base.po
):
msgid "Ja"
msgstr "Yes"
msgid "Nein"
msgstr "No"
msgid "Finden Sie das hier hilfreich?"
msgstr "Do you find this helpful?"
msgid "Stellt eine simple Ja/Nein-Frage"
msgstr "Asks a simple yes/no question"
In unserem Beispiel haben wir absichtlich den String "Vielleicht" weder aufgeführt, noch übersetzt. Dies soll verdeutlichen, dass "Veilleicht" in allen Sprachen unverändert ausgegeben wird.
Anschließend müssen Sie die .po-Dateien nur noch z. B. mit Poedit zur base.mo
kompilieren.
.. note:
Checkbox-Spezialfunktionen
--------------------------
Über die Pluginschnittstelle lassen sich auch Checkboxfunktionen registrieren, welche dann als Spezialfunktion in der
Checkboxverwaltung zur Verfügung stehen.
**Beispiel:**
.. code-block:: xml
<CheckBoxFunction>
<Function>
<Name>Name der Spezialfunktion</Name>
<ID>meinespezialfunktion</ID>
</Function>
</CheckBoxFunction>
Hiermit wird bei einer Plugin-Installation ein neuer Eintrag in die Tabelle `tcheckboxfunktion` geschrieben.
Wird die Checkbox angehakt und ist dafür "*Spezialfunktion Plugin*" gewählt, so wird die jeweilige php-Datei des
Plugins inkludiert.
Frontend-Links
Mit Hilfe von Frontend-Links ist ein Plugin in der Lage, einen Link in JTL-Shop anzulegen
und den Inhalt zu verwalten.
Sie können beliebig viele Elemente des Typs <Link>
anlegen. Falls kein Frontend-Link angegeben wird, sollten Sie
den Block <FrontendLink>
komplett weglassen.
Ab JTL-Shop 5.x werden neue Frontend-Links, unter "Eigene Inhalte" -> "Seiten", der Linkgruppe "Hidden" zugewiesen.
Um nun beispielsweise den Frontend-Link "JTL Test Page" des JTL-Plugins "Demo Plugin" in Ihrem Onlineshop sichtbar zu machen, können Sie ihn aus der Linkgruppe "Hidden" in die Linkgruppe "Megamenu" verschieben. Im Megamenü Ihres Onlineshops wird sodann dieser neue Frontend-Link als letzter Eintrag angezeigt.
Jeder Link kann in beliebig vielen Sprachen lokalisiert werden.
Dazu wird das Element <LinkLanguage>
mit seinem Attribut iso
verwendet. Sein Inhalt wird in Großbuchstaben
geschrieben (z. B.: für Deutsch = GER).
Es werden jedoch immer nur maximal die Sprachen installiert, die der Onlineshop auch beinhaltet.
Hat ein Plugin weniger als die im Onlineshop installierten Sprachen hinterlegt, werden alle weiteren Onlineshopsprachen
mit der Standardsprache aufgefüllt.
Jeder Frontend-Link benötigt eine Smarty-Templatedatei.
Es gibt zwei verschiedene Arten, diese Inhalte anzuzeigen.
Die erste Möglichkeit besteht darin, den Inhalt in einem definierten Bereich (Contentbereich) des Onlineshop
anzuzeigen. Dies wird durch das Element <Template>
erreicht.
Die zweite Möglichkeit wäre, den Inhalt auf einer komplett neuen Seite zu zeigen. Dies benötigt das
Element <FullscreenTemplate>
.
Important
Eine der beiden Varianten muss gesetzt sein.
Es ist nicht möglich, beide Anzeigemöglichkeiten gleichzeitig in der info.xml
zu definieren.
Im folgenden Beispiel wird die Smarty-Templatedatei test_page.tpl
, die sich
im Ordner template/
befindet, im fest definierten Contentbereich des Onlineshops geladen.
<FrontendLink>
<Link>
<Filename>test_page.php</Filename>
<Name>JTL Test Page</Name>
<Template>test_page.tpl</Template>
<VisibleAfterLogin>N</VisibleAfterLogin>
<PrintButton>N</PrintButton>
<Identifier>jtlTestUniqueIdentifier</Identifier><!-- seit Shop 5.1.0 -->
<SSL>2</SSL>
<LinkLanguage iso="GER">
<Seo>jtl-test-page</Seo>
<Name>TestPage</Name>
<Title>TestPage</Title>
<MetaTitle>TestPage Meta Title</MetaTitle>
<MetaKeywords>Test,Page,Meta,Keyword</MetaKeywords>
<MetaDescription>TestPage Meta Description</MetaDescription>
</LinkLanguage>
</Link>
</FrontendLink>
Ein Frontend-Link benötigt keinen expliziten Hook, denn das System bindet den Link automatisch an einem fest definierten Hook.
Link:
Elementname | Funktion |
---|---|
<Filename> * |
Auszuführende Datei beim Link |
<Name> * |
Name des Links ([a-zA-Z0-9 ]+ ) |
<Template> * |
Smarty-Templatedatei die den Linkinhalt anzeigt |
<FullscreenTemplate> * |
Smarty-Templatedatei die den Linkinhalt anzeigt |
<VisibleAfterLogin> * |
Nur anzeigen wenn der User eingeloggt ist ([NY]{1,1}) |
<PrintButton> * |
Druckbutton anzeigen ([NY]{1,1}) |
<NoFollow> * |
NoFollow-Attribut in den HTML Code einfügen ([NY]{1,1}) |
<LinkLanguage> * |
|
<Identifier> |
Unveränderbare ID, seit 5.1.0 ([a-zA-Z0-9 ]+ ) |
<SSL> |
0 oder 1 für Standard, 2 für erzwungenes SSL |
LinkLanguage
Elementname | Funktion |
---|---|
<iso> * |
Sprach.ISO ([A-Z]{3} ) |
<Seo> * |
SEO-Name des Links ([a-zA-Z0-9 ]+ ) |
<Name> * |
Name des Links ([a-zA-Z0-9 ]+ ) |
<Title> * |
Titel des Links ([a-zA-Z0-9 ]+ ) |
<MetaTitle> * |
Meta Title des Links ([a-zA-Z0-9,. ]+ ) |
<MetaKeywords> * |
Meta Keywords des Links ([a-zA-Z0-9, ]+ ) |
<MetaDescription> |
Meta Description des Links ([a-zA-Z0-9,. ]+ ) |
(*) Pflichtfeld
Zahlungsmethoden
Das Pluginsystem von JTL-Shop ist in der Lage, eine oder mehrere Zahlungsmethoden zugleich
zu implementieren. Dabei wird nicht in den Code von JTL-Shop eingegriffen.
Das Hauptelement <PaymentMethod>
wird unter dem Element <Install>
eingefügt. Es kann beliebig viele
Zahlungsmethoden (<Method>
) enthalten.
Falls das Plugin keine Zahlungsmethode implementieren soll, wird der <PaymentMethod>
Block ganz weggelassen.
<Install>
...
<PaymentMethod>
...
</PaymentMethod>
...
</Install>
Elementname | Funktion |
---|---|
<Method> * |
Zahlungsmethode |
(*) Pflichtfeld
Beispiel
<Method>
<Name>PayPal Plus</Name>
<PictureURL>images/de-ppcc-logo-175px.png</PictureURL>
<Sort>1</Sort>
<SendMail>1</SendMail>
<Provider>PayPal</Provider>
<TSCode>PAYPAL</TSCode>
<PreOrder>1</PreOrder>
<Soap>0</Soap>
<Curl>1</Curl>
<Sockets>0</Sockets>
<ClassFile>PayPalPlus.php</ClassFile>
<ClassName>PayPalPlus</ClassName>
<TemplateFile>template/paypalplus.tpl</TemplateFile>
<MethodLanguage iso="GER">
<Name>PayPal, Lastschrift, Kreditkarte oder Rechnung</Name>
<ChargeName>PayPal PLUS</ChargeName>
<InfoText>PayPal, Lastschrift, Kreditkarte oder Rechnung</InfoText>
</MethodLanguage>
<Setting type="text" initialValue="" sort="1" conf="Y">
<Name>Anzeigename für PayPal Login</Name>
<Description>Verwendeter Name auf der PayPal-Seite</Description>
<ValueName>brand</ValueName>
</Setting>
</Method>
Elementname | Funktion |
---|---|
<Name> * |
Name der Zahlungsmethode |
<PictureURL> * |
Link zu einem Logo |
<Sort> * |
Sortierungsnummer der Zahlungsmethode ([0-9]+ ) |
<SendMail> * |
Versand einer E-Mail bei Zahlungseingang (1 = "Ja", 0 = "Nein") |
<Provider> |
Zahlungsanbieter |
<TSCode> * |
Trusted Shops TSCode([A-Z_]+ ) |
<PreOrder> * |
Pre(1)- oder Post(0)-Bestellung([0-1]{1} ) |
<Soap> * |
Übertragungsprotokoll Flag ([0-1]{1} ) |
<Curl> * |
Übertragungsprotokoll Flag ([0-1]{1} ) |
<Sockets> * |
Übertragungsprotokoll Flag ([0-1]{1} ) |
<ClassFile> * |
Name der Datei der PHP-Klasse ([a-zA-Z0-9\/_\-.]+.php ) |
<ClassName> * |
Name der Klasse |
<TemplateFile> |
Name der Templatedatei ([a-zA-Z0-9\/_\-.]+.tpl ) |
<AdditionalTemplateFile> |
Templatedatei für einen Zusatzschritt |
<MethodLanguage> * |
Lokalisierung der Zahlungsmethode |
<Setting> |
Einstellungen der Zahlungsmethode |
(*) Pflichtfelder
Die Elemente <Soap>
, <Curl>
und <Sockets>
benennen die erforderlichen Kommunikationswege zum Server
des Zahlungsanbieters, die von diesem Zahlungsmethodenplugin genutzt werden sollen.
Diese Elemente werden bei der Installation des Plugins vom Plugin-System des Shops geprüft und mit den vorhandenen
Möglichkeiten des aktuellen Shop-Servers abgeglichen (z. B. das Vorhandensein entsprechender PHP-Module). Die Prüfung
erfolgt hierbei in einer ODER-Verknüpfung.
D.h. sobald eine der geforderten Übertragungarten zum Server des Zahlungsnabieters verfügbar ist, wird auch das
Zahlungsmethodenplugin nach der Installation als arbeitsfähig markiert.
In einigen Fällen werden jedoch mehrere Übertragungswege benötigt, beispielsweise SOAP zur Nutzerdatenübertragung
und CURL für Liquiditätsprüfungen. Das Plugin-System prüft jedoch standardmäßig nicht, ob alle benötigten
Übertragungswege zur Verfügung stehen. Deshalb müssen Sie selbst programmatisch dafür sorgen (z. B. mithilfe der
Methode "isValidIntern()"), dass das Plugin dem Plugin-System
mitteilt, wenn nicht alle benötigten Übertragungswege verfügbar sind.
Falls das Zahlungsplugin dagegen z.B. auf einem POST-Formular aufgebaut ist, kann man hier jedem Element
eine 0
zuweisen.
Im Element <TemplateFile>
kann der Name oder Pfad zu einer Smarty Template-Datei angegeben werden.
Dort können dann z.B. POST-Formulare ausgegeben werden.
Im Element <AdditionalTemplateFile>
können Sie außerdem eine Smarty-Templatedatei für einen zusätzlichen
Zahlungsschritt angeben. Hier können z. B. Kreditkarteninfos abgefragt werden.
Das Element <TSCode>
kann folgende Werte enthalten: "DIRECT_DEBIT", "CREDIT_CARD", "INVOICE",
"CASH_ON_DELIVERY", "PREPAYMENT", "CHEQUE", "PAYBOX", "PAYPAL", "CASH_ON_PICKUP", "FINANCING",
"LEASING", "T_PAY", "CLICKANDBUY", "GIROPAY", "GOOGLE_CHECKOUT", "SHOP_CARD", "DIRECT_E_BANKING",
"OTHER".
Der XML-Knoten <MethodLanguage>
sorgt für die Mehrsprachigkeit der Zahlungsmethode.
Sie können beliebig viele Sprachen für eine Zahlungsmethode implementieren. Eine Sprache muss jedoch mindestens
enthalten sein.
Elementname | Funktion |
---|---|
<iso> * |
Sprachcode der jeweiligen Sprache |
<Name> * |
Name der Zahlungsmethode |
<ChargeName> * |
Sortierungsnummer der Zahlungsmethode ([0-9]+ ) |
<InfoText> * |
Kurzbeschreibung der Zahlart, wie sie im Frontend angezeigt wird |
(*) Pflichtfelder
Der XML-Knoten <Setting>
ermöglicht es dem Plugin, spezifische Einstellungen des Onlineshopbetreibers
entgegenzunehmen.
Jede Zahlungsmethode kann beliebig viele Einstellungen enthalten, z.B. die Logindaten für einen bestimmten
Onlineshopbetreiber. Diese Einstellungen werden im Backend bei der jeweiligen Zahlungsmethode angezeigt und können dort
editiert werden.
Elementname | Funktion |
---|---|
<type> * |
Einstellungstyp (text, zahl, selectbox) |
<initValue> * |
Vorausgewählte Einstellung |
<sort> * |
Sortierung der Einstellung (höher = weiter unten) |
<conf> * |
Y = echte Einstellung, N = Überschrift |
<Name> * |
Name der Einstellung |
<Description> * |
Beschreibung der Einstellungsvariable |
<ValueName> * |
Name der Einstellungsvariable |
<SelectboxOptions> |
Optionales Element bei type = selectbox |
(*) Pflichtfelder
Weitere Informationen zum Thema "Zahlungsarten im Plugin" finden Sie im Kapitel "Zahlungs-Plugins".
Sprachvariablen
Sprachvariablen sind lokalisierte Variablen, die für verschiedene Sprachen hinterlegt und abgerufen werden können. Sofern die Sprachen von JTL-Shop und die Sprachen des Plugins übereinstimmen, passen sich die Sprachvariablen für jede eingestellte Sprache im Onlineshop automatisch lokalisiert an. Sollte das Plugin Frontend-Links bereitstellen, so sollte jede textuelle Ausgabe mittels dieser Sprachvariablen ausgegeben werden.
Note
Sprachvariablen sind nicht zu verwechseln mit den "Übersetzung von Settings", im Backend des Onlineshops.
Anpassung der Sprachvariablen in den Plugineinstellungen des Adminbereichs
Sprachvariablen können nach der Installation eines Plugins vom Betreiber des Onlineshops angepasst werden. Zu diesem Zweck stellt die Pluginverwaltung die Spalte "Sprachvariablen" bereit, in der sich die Schaltfläche "Bearbeiten" befinden kann, sobald ein Plugin Sprachvariablen bereitstellt.
Ein Plugin kann beliebig viele Sprachvariablen definieren.
Das Hauptelement der Sprachvariablen heißt <Locales>
und jede Sprachvariable wird im Element <Variable>
definiert.
<Locales>
ist ein Unterknoten von <Install>
.
Im XML-Container <Variable>
können beliebig viele <VariableLocalized>
-Knoten eingebunden werden.
<Locales>
<Variable>
<Name>xmlp_lang_var_1</Name>
<Description>Eine Beispiel-Variable.</Description>
<VariableLocalized iso="GER">PI ist %s und Parameter 2 lautet: %s.</VariableLocalized>
<VariableLocalized iso="ENG">PI is %s and parameter 2 has the value: %s.</VariableLocalized>
</Variable>
<Variable>
<Description>Eine weitere Beispiel-Variable.</Description>
<Name>xmlp_lang_var_2</Name>
<VariableLocalized iso="GER">Ich bin variabel!</VariableLocalized>
<VariableLocalized iso="ENG">I'm variable!</VariableLocalized>
<Type>textarea</Type>
</Variable>
</Locales>
Elementname | Funktion |
---|---|
<Name> * |
Name der Sprachvariable |
<Description> * |
Beschreibung der Sprachvariable |
<VariableLocalized> * |
Lokalisierter Name |
<Type> |
Typ des Eingabefeldes (ab 5.0.0) |
(*) Pflichtfelder
Hint
Diesbezügliche Änderungen an der info.xml
sind erst nach einer Neuinstallation des Plugins sichtbar, da die
Variablen bei der Installation in die Datenbank geschrieben werden.
Die Angabe des Typs ist seit Shop 5.0.0 möglich, aber optional. Standardmäßig wird er auf "text" gestellt, was einem einfachen Texteingabefeld im Backend entspricht. Für längere Texte bietet sich der Typ "textarea" an. Prinzipiell lassen sich hier alle in JTL\Plugin\Admin\InputType definierten Typen nutzen.
Sprachvariablen können auf ihren Ursprungswert zurückgesetzt werden. Bei einem Pluginupdate oder beim Deaktivieren eines Plugins bleiben die Sprachvariablen erhalten, die durch den Betreiber des Onlineshops angepasst wurden. Erst bei einer Deinstallation des Plugins werden die Sprachvariablen endgültig gelöscht.
Nutzung im Plugin
Es sei folgendes Beispiel-XML gegeben:
<jtlshopplugin>
...
<PluginID>jtl_example_plugin</PluginID>
</jtlshopplugin>
<Install>
<Locales>
<Variable>
<Name>lang_var_one</Name>
<VariableLocalized iso="GER">Ich bin variabel!</VariableLocalized>
<VariableLocalized iso="ENG">I'm variable!</VariableLocalized>
<Description>Eine Beispiel-Variable.</Description>
</Variable>
<Variable>
<Name>lang_var_two</Name>
<Description>Eine Beispiel-Variable mit Platzhalter.</Description>
<VariableLocalized iso="GER">Hallo, mein Name ist %s.</VariableLocalized>
<VariableLocalized iso="ENG">Hello, my name is %s.</VariableLocalized>
</Variable>
</Locales>
...
</Install>
Der Wert der Sprachvariablen kann via PHP auf folgende Weise ausgegeben werden:
JTL-Shop 5.x
// z.B. innerhalb der Bootstrap.php in der Boot-Methode:
$plugin = $this->getPlugin();
$test1 = $plugin->getLocalization()->getTranslation('lang_var_one');
$test2 = \sprintf($plugin->getLocalization()->getTranslation('lang_var_two'), 'Peter');
Ab Shop 5.1.0 können Sprachvariablen direkt innerhalb von Templatedateien genutzt werden.
Nutzen Sie dafür die Syntax {lang key='variablen-name' section='meine-plugin-id'}
- im Beispiel also
{lang key='lang_var_one' section='jtl_example_plugin'}
{lang key='lang_var_two' section='jtl_example_plugin' printf='Peter'}
E-Mail-Templates
Ein Plugin kann auch neue E-Mail-Typen definieren, die als E-Mail versendet werden können. Dabei kann der E-Mail-Inhalt eines Templates für alle im Onlineshop verfügbaren Sprachen vorbelegt werden. Die vordefinierten Texte sind weiterhin in der E-Mail-Vorlagenverwaltung im Backend durch den Betreiber des Onlineshops editierbar.
Der Hauptknoten <Emailtemplate>
, welcher im Container <Install>
liegt, definiert eine neue E-Mailvorlage.
<Emailtemplate>
<Template>
<Name>Zahlungs-Erinnerungsemail</Name>
<Description></Description>
<Type>text/html</Type>
<ModulId>zahlungserinnerung</ModulId>
<Active>Y</Active>
<AKZ>0</AKZ>
<AGB>0</AGB>
<WRB>0</WRB>
<TemplateLanguage iso="GER">
<Subject>Zahlungserinnerung</Subject>
<ContentHtml></ContentHtml>
<ContentText></ContentText>
</TemplateLanguage>
<TemplateLanguage iso="ENG">
<Subject>Reminder</Subject>
<ContentHtml></ContentHtml>
<ContentText></ContentText>
</TemplateLanguage>
</Template>
</Emailtemplate>
Element | Funktion |
---|---|
<Template> |
Hauptcontainerelement (pro E-Mail-Vorlage muss es ein Element <Template> geben) |
<Name> |
Name der E-Mail-Vorlage |
<Description> |
Beschreibung der E-Mail-Vorlage |
<Type> |
Sendeformat der E-Mail-Vorlage (html/text oder text) |
<ModulId> |
Eindeutiger Schlüssel der E-Mail-Vorlage |
<Active> |
Aktivierungsflag der E-Mail-Vorlage (Y/N) |
<AKZ> |
Anbieterkennzeichnung in der E-Mail-Vorlage anhängen (1/0) |
<AGB> |
Allgemeine Geschäftsbedingungen in der E-Mail-Vorlage anhängen (1/0) |
<WRB> |
Widerrufsbelehrung in der E-Mail-Vorlage anhängen (1/0) |
<TemplateLanguage> |
Lokalisierte Inhalte pro Sprache (min. eine Sprache muss vorhanden sein) (Key = SprachISO) |
<Subject> |
Betreff der E-Mail-Vorlage in der jeweiligen Sprache |
<ContentHtml> |
Inhalt als HTML |
<ContentText> |
Inhalt als Text |
(*) Pflichtfeld
Weitere Informationen zum Thema "E-Mail-Templates im Plugin" finden Sie im Kapitel "Mails".