Zum Hauptinhalt gehen
Academy Community Anmelden

Smarty Anleitung

  • Aktualisiert

Inhaltsverzeichnis

Hinter Smarty verbirgt sich eine Technik, die es ermöglicht, schnell und übersichtlich Daten zu konvertieren. Dabei gilt: Alle textbasierten Formate können konvertiert werden, gleich ob es sich um CSV-, XML, JSON- oder anders strukturierte Dateien handelt.

Smarty kann an verschiedenen Stellen in xentral genutzt werden

  • Smarty im Übertragen-Modul
  • Smarty in Shop-Schnittstellen

Die verfügbaren Funktionen und dazugehörigen Modifier sind zum großen Teil identisch. Auf Besonderheiten weisen wir daher in den entsprechenden Abschnitten der Dokumentation hin. Smarty ist in xentral an den entsprechenden Stellen bereits enthalten. Das Herunterladen von Libraries ist nicht notwendig.

Grundlagen

Vorgehensweise

Basis der Umwandlung ist immer das sog. Smarty Template. Darin wird das Format und die Struktur des ausgehenden Dokumentes definiert. Dazu kann einfach das Zielformat in Form einer Beispieldatei in den Template-Editor kopiert werden. Anschließend werden die Beispieldaten durch Variablen ersetzt und können dann vom System gefüllt werden.

Am Beispiel eines Auftrages als XML-Datei wird hier verdeutlicht wie diese Umwandlung stattfinden kann.

Das folgende Format soll ausgegeben werden:

<?xml version="1.0" encoding="utf-8"?>

<auftrag>

  <belegnr>200259</belegnr>

  <kundennummer>100112</kundennummer>

  <name>Max Musterman</name>

  <strasse>Beispielstrasse 13</strasse>

  <plz>86150</plz>

  <ort>Augsburg</ort>

  <positionen>

<position>

<nummer>Art_001</nummer>

   <bezeichnung>Beispielartikel 1</bezeichnung>

   <menge>3</menge>

   <preis>7.96</preis>

</position>

<position>

<nummer>Art_002</nummer>

   <bezeichnung>Beispielartikel 2</bezeichnung>

   <menge>10</menge>

   <preis>399.99</preis>

</position>

  </positionen>

</auftrag>

 

Diese Beispieldatei wird in den Template-Editor kopiert. Anschließend werden die Beispielwerte mit den zugehörigen Variablen ersetzt.

<?xml version="1.0" encoding="utf-8"?>

<auftrag>

  <belegnr>{$beleg->belegnr}</belegnr>

  <kundennummer>{$beleg->kundennummer}</kundennummer>

  <name>{$beleg->name}</name>

  <strasse>{$beleg->strasse}</strasse>

  <plz>{$beleg->plz}</plz>

  <ort>{$beleg->ort}</ort>

  <positionen>

  {foreach from=$beleg->positionen key=keyrow item=position}{* Positionen *}

  <position>

<nummer>{$position->nummer}</nummer>

   <bezeichnung>{$position->bezeichnung}</bezeichnung>

   <beschreibung>{$position->beschreibung}</beschreibung>

   <menge>{$position->menge}</menge>

   <preis>{$position->preis}</preis>

   <einheit>{$position->einheit}</einheit>

</position>

  {/foreach}

  </positionen>

</auftrag>

 

Dabei wird je nach Bereich ein Basisobjekt verwendet, um auf die Werte zuzugreifen. Je nach Einsatzgebiet ist das ein anderes Objekt:

  • $beleg → Genutzt im Übertragen-Modul, um ausgehende Belegdaten zu verarbeiten
  • $artikelliste → Genutzt im Übertragen-Modul, um ausgehende Artikel oder Lagerbestände (Lagerzahlen) zu verarbeiten
  • $trackingliste → Übertragen-Modul - Ausgehende Trackinginformationen verarbeiten
  • $salesreportlist → Übertragen-Modul - Ausgehende Belegdaten verarbeiten
  • $object → Im Übertragen-Modul werden eingehende Daten verarbeitet
  • $cart → In der Shop-Schnittstelle genutzt, um den Warenkorb zu verarbeiten

Funktionen und Modifier

Alle hier beschriebenen Beispiele stammen aus dem Standard-Umfang der verwendeten Template-Engine Smarty. Weitere Funktionen finden sich daher in der offiziellen Smarty-Dokumentation: https://www.smarty.net/docs/en/language.modifiers.tpl

Zahlendarstellung

Nachkommastellen kürzen

Zahl soll auf 3 Nachkommastellen gekürzt werden. Anschließend soll der Punkt durch ein Komma ersetzt werden. Anstelle einer Zahl kann natürlich auch eine Variable oder das Ergebnis einer Berechnung sein.

Template: 

{1.12345|string_format:"%1\$.3f"|replace:".":","}

Ergebnis: 1,123

Weitere Definitionen finden sich auch den Dokumentation des Smarty Modifiers string_format.

Textformatierung

Textlänge begrenzen

Sollte beispielsweise im Warenkorb ein langer Textwert für den Namen (order => name =>) “Max Mustermann” importiert werden, könnte dieser auch mit Hilfe von Smarty auf eine feste Textlänge (in Zeichen) gekürzt werden.

Template:

 {$cart->order->name|truncate:6}

Ergebnis: Max…

Weitere Definitionen finden sich auch den Dokumentation des Smarty Modifiers truncate

Bedingungen

Mit Hilfe von Bedingungen kann bereits im Template mit Logik gearbeitet werden, um kundenspezifische Entscheidungen bereits beim Ex- oder Import von Daten in verschiedene Ergebnisse zu überführen.

Im Folgenden Beispiel wird beim Import eines Auftrages über eine Shop-Schnittstelle der englische Wert “mr” in die Anrede “herr” überführt, die in xentral für den Adresstyp und die Anrede “Herr” steht.

Beispiel Shopimporter:

<xml>

  <name>Max Mustermann</name>

  {if $cart->order->salutation == “mr”}

    <anrede>herr</anrede>

  {else}

    <anrede>frau</anrede>

  {/if}

</xml>


Alternative Schreibweise (Shopimporter)

<xml>
  <name>Max Mustermann</name>
  <anrede>
  {if $cart->order->Salutation == “mr”}
    herr{else}frau{/if}
  </anrede>
</xml>

 

Weitere alternative Schreibweise zum Überschreiben eines Knotens (Shopimporter)

<xml>
  <name>Max Mustermann</name>
  <anrede>frau</anrede>
  {if $cart->order->salutation == “mr”}
    <anrede>herr</anrede>
  {/if}
</xml>


In diesem Beispiel überschreibt der zweite gleich lautende Knoten (anrede) bei Zutreffen der Bedingung den vollständigen ersten Knoten inkl. Wert und ersetzt so den Inhalt.

Weitere Definitionen finden sich auch den Dokumentation des Smarty if/else

Schleifen

Schleifen ermöglichen die Abarbeitung von Wertelisten (Arrays), z.B. Auftragspositionen, Steuersätze, o.ä. Ergebnis sind meist Key-Value-Pairs, die dann im zweiten Schritt ausgewertet werden können. Dazu werden diese Listen in einer Schleife durchlaufen und bearbeitet.

Im folgenden Beispiel wird für eine gegebene Struktur der Rechnungsadresse ein beliebiges Element herausgegriffen um z.B. eine gesonderte Einstellung für das Land zu setzen. 

Beispiel Shopimporter

Warenkorb: 

...

billing => [

  0 => [name => country, value => DE],

  1 => [name => street, value => Musterweg],

  2 => [name => house_no, value => 2],

  3 => [name => phone, value => 123456789],

  4 => [name => first_name, value => Max],

...

 

Template:

<xml>

  {foreach key=billingKey item=billingData from=$cart->billing}

    {if $billingData->name == ”country”}

      <land>{$billingData->value}</land>

    {/if}

  {/foreach}

</xml>

 

Weitere Definitionen finden sich auch den Dokumentation von Smarty zu Schleifen am Beispiel foreach

Tipps und Tricks

Letztes Element einer Schleife

Gerade bei der Ausgabe von JSON oder XML-Listen kann es wichtig sein das Listenelement sauber abzuschließen. Um invalide Datenstrukturen zu erhalten, müssen alle Elemente mit einem Komma abgeschlossen werden, die nicht am Schluß der Liste stehen. Dazu kann die Syntax $item@last verwendet werden.

Beispiel

Ausgabe einer JSON-Datei mit dem Artikelbestand

{"SELECT * ... "|assignsql assign="stock"}

​​{

  "stock": [

    {foreach from=$stock key=keyrow item=st}

      {

        "materialId": "{$st->nummer}",

        "quantity": "{$st->menge}",

        "warehouse": "{$st->kurzbezeichnung}"

​      },

​

      {if $st@last}

      {

        "materialId": "{$st->nummer}",

        "quantity": "{$st->menge}",

        "warehouse": "{$st->kurzbezeichnung}"

​      }

​      {/if}

    {/foreach}

]}

Smarty im Übertragen-Modul

Das Übertragen-Modul ermöglicht es eine Vielzahl von Belegen oder Daten aus xentral zu exportieren. Dabei werden neben verschiedenen Ausgabeformaten und Ausgabekanälen auf verschiedene Trigger zum Export angeboten (z.B. der Belegstatus, Label, ID oder Datum eines Beleges, etc.). Dazu wird das Smarty Transfer-Modul verwendet.

Mit Hilfe von Smarty kann nun das Zielformat der ausgegebenen Daten selbst definiert werden und mit Hilfe von 

  • Funktionen (wie z.B. truncate) bearbeitet,
  • mit SQL-Abfragen angereichert
  • und durch die Anwendung von Schleifen, Bedingungen o.ä. mit Logik 

verändert werden.

Im Übertragen-Modul steht Smarty bei eingehenden und ausgehenden Nachrichten zur Verfügung. Dabei bestimmt das Template 

  • bei ausgehenden Nachrichten das von der Gegenstelle erwartete Zielformat 
  • bei eingehenden Nachrichten das xentral interne Format zur Verarbeitung (in den meisten Fällen xentral XML).

 

Smarty Ausgehend (outbound oder Export)

Daten aus xentral zu versenden (auch “outbound” genannt) ermöglicht es die Daten von xentral 

  1. in ein Zielformat zu konvertieren und anschließend 
  2. in ein Fremdsystem zu exportieren.

Eine Template-Datei könnte dabei z.B. folgendermaßen aussehen:

<?xml version="1.0" encoding="utf-8"?>

<auftrag>

  <status>{$beleg->status}</status>

  <datum>{$beleg->datum|date_format:'%d.%m.%Y'}</datum>

  <lieferdatum>{$beleg->lieferdatum}</lieferdatum>

  <versandart>{$beleg->versandart}</versandart>

  <zahlungsweise>{$beleg->zahlungsweise}</zahlungsweise>

  <belegnr>{$beleg->belegnr}</belegnr>

  <kundennummer>{$beleg->kundennummer}</kundennummer>

  <name>{$beleg->name}</name>

  <strasse>{$beleg->strasse}</strasse>

  <plz>{$beleg->plz}</plz>

  <ort>{$beleg->ort}</ort>

  <positionen>

  {foreach from=$beleg->positionen key=keyrow item=position}{* Positionen *}

  <position>

<nummer>{$position->nummer}</nummer>

   <bezeichnung>{$position->bezeichnung}</bezeichnung>

   <beschreibung>{$position->beschreibung}</beschreibung>

   <menge>{$position->menge}</menge>

   <preis>{$position->preis}</preis>

   <einheit>{$position->einheit}</einheit>

</position>

  {/foreach}

  </positionen>

   {if $beleg->versand}

   <tracking>

   {foreach from=$beleg->versand key=keyversand item=tracking}{* Versand *}

<tracking>{$tracking->tracking}</tracking>

   {/foreach}

   </tracking>

{/if}

</auftrag>

Smarty Eingehend (inbound oder Import)

Daten in xentral einzulesen (auch “inbound” genannt) ermöglicht es die Daten 

  1. aus einem anderen System zu importieren, 
  2. zu interpretieren, dann 
  3. in ein xentral Zielformat zu konvertieren und anschließend 
  4. in xentral zu importieren.

Besonderheiten im Übertragen-Modul

Verknüpfte Belege

In allen Belegen kann mit Hilfe von Smarty auf verknüpfte Belege zugegriffen werden. Wenn z.B. zu einem Auftrag ein Lieferschein existiert, existiert auch ein Array $beleg->lieferschein[] in dem dann die entsprechenden Informationen des referenzierten Lieferscheines zur Verfügung stehen. Auf diese Art kann schnell auf ergänzende Belegnummern, Lieferdaten, Chargen oder Seriennummern zurückgegriffen werden - auch bei der Erstellung eines Auftrages. Die Lieferscheinnummer z.B. wäre direkt erreichbar über $beleg->lieferschein[0]->belegnr

Die folgenden Daten stehen in den jeweiligen Belegen zur Verfügung, sofern ein entsprechender Beleg im System existiert.

Im Auftrag:

  • $beleg->bestellung[]
  • $beleg->angebot[]
  • $beleg->lieferschein[]
  • $beleg->rechnung[]
  • $beleg->retoure[]
  • $beleg->gutschrift[]

Im Lieferschein:

  • $beleg->bestellung[]
  • $beleg->rechnung[]

In der Rechnung:

  • $beleg->bestellung[]
  • $beleg->lieferschein[]

SQL-Abfragen

Im Übertragen-Modul können zur Anreicherung von Daten auch allgemeine SQL-Anfragen erstellt und in den ausgegebenen Templates ausgegeben werden. Dazu wird folgender Syntax verwendet:

{"SELECT gln, rechnung_gln FROM adresse where lieferantennummer = 
'{$beleg->lieferantennummer}' "|assignsql assign="adressdata"}

 

Der Zugriff auf das Ergebnis kann dann über das zugewiesene Array adressdata  vorgenommen werden:

{$adressdata[0]->gln} // für den gezielten Aufruf des Arrays

Verwandte Beiträge



Verwandte Community Beiträge