Shopware Tipps & Tricks – Anpassung pluginspezifischer Dokumentenvorlagen

Herzlich willkommen zum bereits achten Teil unserer Reihe Shopware Tipps & Tricks!

In der Vergangenheit sind Kunden häufig mit Problemen an uns herangetreten, die mit der Anpassung pluginspezifischer Dokumentenvorlagen in Verbindung standen. Deshalb möchten wir heute den aus unserer Sicht korrekten Umgang bei der Individualisierung solcher Dokumentenvorlagen zusammenfassen und Ihnen die Hintergründe erklären.

Relevantes Hintergrundwissen

Da die pluginspezifischen Dokumentenvorlagen auf der gleichen Logik wie die Shopware Standardtemplates basieren, sollten Sie sich vorher mit dem allgemeinen Shopware Templating auseinandersetzen. Ebenso sollten Sie ein Verständnis über Vererbungsstrukturen von Templates haben.

Problembeschreibung

Sie haben die Dokumentenvorlage eines Plugins an Ihre eigenen Bedürfnisse angepasst, es wird aber dennoch das alte Template verwendet? Woran das liegen kann, möchten wir an einem Beispiel erklären. Dafür werfen wir einen Blick in unser Mahnwesen Plugin und dessen Standarddokument für die Mahnung erster Stufe:

Wo werden die Dokumentenvorlagen hinterlegt?

Die Dokumentenvorlage ist für das entsprechenden Dokument in der Shopware PDF-Belegerstellung hinterlegt. In unserem Beispiel also unter Einstellungen > Grundeinstellungen > Shopeinstellungen > PDF-Belegerstellung > “Mahnung Stufe 1”.

Wird ein entsprechendes Dokument generiert, wird auf die Vorlage zurückgegriffen, welche unter Template hinterlegt ist (im Beispiel: reminderlevelone.tpl). Diese wird nach einem festgelegten Schema, anhand einer Hierarchie von Suchorten gesucht. Die dabei zuerst gefundene Vorlage wird gerendert. Selbstverständlich wird hierbei auch die Vererbungshierarchie des Templates berücksichtigt. Die Suchhierarchie zu verstehen, ist demnach sehr wichtig für das erfolgreiche Anpassen der Dokumentenvorlagen.

Wie ist die Suchhierarchie im Falle von Dokumentenvorlagen aufgebaut?

Abhängig davon, worauf die Variable $injectBeforePlugins in Ihrer theme.php gesetzt ist, gibt es zwei Möglichkeiten wie die Suchhierarchie im Falle von Dokumentenvorlagen aufgebaut ist.

Ist $injectBeforePlugins auf false gesetzt (Suchhierarchie A), wird zunächst das Dokumenten-Theme nach dem Template durchsucht. Anschließend werden alle Plugins durchsucht und bei erfolgreicher Suche wird das zuerst gefundene Template verwendet.

Ist $injectBeforePlugins auf true gesetzt (Suchhierarchie B), werden zuerst alle Plugins nach dem Dokumententemplate durchsucht. Sobald die Suche erfolgreich war, wird sie abgebrochen und das gefundene Template gerendert.

Die Datei Ihrer eigenen angepassten Vorlage hinterlegen Sie in dem von Ihnen verwendeten shopspezifischen Dokumententemplate, welches Sie unter Einstellungen > Grundeinstellungen > Shops > “Dokumenten-Template” konfiguriert haben. Die Datei der pluginspezifischen Dokumentenvorlage liegt jedoch im Plugin selbst. Somit spielt es eine wichtige Rolle, wo mit der Suche nach dem Template begonnen wird. Das Ganze möchten wir an Hand unseres Beispiels verdeutlichen.

Wie sollte das Dokument angepasst werden?

Um eine bestehende Dokumentenvorlage zu bearbeiten, müssen Sie nicht die gesamte Template-Datei kopieren oder diese überschreiben. Es empfiehlt sich das Template-Vererbungssystem zu nutzen. So müssen Sie nur die Teile bearbeiten, die Sie wirklich ändern möchten.

Beispiel: Anpassung der Dokumentenvorlage der Mahnung Stufe 1 Wir möchten nun, dass die Tabelle unserer Mahnung Stufe 1 unterhalb der Überschrift angezeigt wird. Dafür erstellen wir eine entsprechende eigene Dokumentenvorlage, die von der Dokumentanvorlage des Mahnwesen Plugins erbt und speichern diese unter einem eigenen Namen (reminderlevelone_custom.tpl). In dieser Dokumentenvorlage müssen wir somit lediglich die bereits existierenden Elemente so anpassen, dass unsere Tabelle direkt nach der Überschrift angezeigt wird:

{*
Inherit form the default document template for level one reminders,
which is defined inside the dunning plugin.
*}
{extends file="parent:documents/reminderlevelone.tpl"}

{* Rearrange blocks: move table up below headline *}
{block name="document_reminder_content"}
    {capture name="document_reminder_content"}
        {$smarty.block.parent}
    {/capture}
{/block}
{block name="document_reminder_content_table"}
    {$smarty.block.parent}
    <br>
    {$smarty.capture.document_reminder_content}
{/block}
{* Hide differing shipping address info *}
{block name="document_invoice_differing_shipping_address"}{/block}

Nun tragen wir unsere eigene Dokumentenvorlage reminderlevelone_custom.tpl in Einstellungen > Grundeinstellungen > Shopeinstellungen > PDF-Belegerstellung > “Mahnung Stufe 1” in das Template Feld ein. Die Verwendung eines eigenen Namens für die eigene Vorlage ist hier besonders wichtig, um Probleme mit der Suchhierarchie zu vermeiden. Verwendet man nämlich den gleichen Namen für das eigene Template wird bei Suchhierarchie B (Shopware Standard) zuerst die Dokumentenvorlage des Plugins gefunden und gerendert. Die eigene Vorlage wird in diesem Fall gar nicht erst gefunden und somit bei der Erzeugung des Dokuments auch nicht berücksichtigt.

Es ist somit zu empfehlen der eigenen Dokumentenvorlage immer einen neuen Namen zu geben, damit es in keinem Fall zu Problemen mit der Suchhierarchie kommen kann.

In unserem Fall wird nun unabhängig von Suchhierarchie A oder B zunächst nach der Template-Datei reminderlevelone_custom.tpl gesucht und diese wird im Dokumenten-Theme gefunden. Da diese Datei von der ursprünglichen Template-Datei reminderlevelone.tpl erbt, werden die Suchorte in einem zweiten Schritt nach dieser Datei durchsucht. Die Datei wird im Plugin gefunden und das Dokument wie von uns gewünscht erzeugt:

Wir hoffen wir konnten Ihnen mit dem heutigen Blogpost weiterhelfen. Viel Spaß beim Ausprobieren und bis zum nächsten Teil unserer Reihe!

Zur Übersicht

Teilen