Zum Hauptinhalt gehen
Academy Community Anmelden

Smarty Anleitung

  • Aktualisiert

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 '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} 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 '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} 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"?>

<order>

<order no>200259</order no>

<customer number>100112</customer number>

<name>Max Musterman</name>

<street>Samplestreet 13</street>

<plz>86150</plz>

<location>Augsburg</location>

<positions>

<position>

<number>Art_001</number>

 <name>example item 1</name>

 <quantity>3</quantity>

 <price>7.96</price>

</item>

<position>

<number>Art_002</number>

 <name>example item 2</name>

 <quantity>10</quantity>

 <price>399.99</price>

</item>

</items>

</order>

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"?>

<order>

<order number>{$voucher->order number}</order number>

<customer number>{$voucher->customer number}</customer number>

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

<street>{$claim->street}</street>

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

<location>{$document->location}</location>

<items>

{foreach from=$voucher->positions key=keyrow item=position}{* positions *}

 <position>

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

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

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

 <quantity>{$item->quantity}</quantity>

 <price>{$item->price}</price>

 <unit>{$item->unit}</unit>

</position>

{/foreach}

</positions>

</order>

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 verarbeiteninformation

  • $salesreportlist → Übertragen-Modul - Ausgehende Belegdaten verarbeitenData

  • $object → Im Übertragen-Modul werden eingehende Daten verarbeitetmodule

  • $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 =&gt; name =&gt;) “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 '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} für den Adresstyp und die Anrede “Herr” steht.

Beispiel Shopimporter:

<xml>

<name>Max Mustermann</name>

{if $cart->order->salutation == "mr"}

<salutation>mr</salutation>

{else}

<address>woman</address>

{/if}

</xml>

Alternative Schreibweise (Shopimporter)

<xml>
<name>Max Mustermann</name>
<salutation>
{if $cart->order->salutation == "mr"}
mr{else}wife{/if}
</address>
</xml>

Weitere alternative Schreibweise zum Überschreiben eines Knotens (Shopimporter)

<xml>
<name>Max Mustermann</name>
<salutation>wife</salutation>
{if $cart->order->salutation == "mr"}
<address>gentleman</address>
{/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 Documentation of the 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"}

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

{/if}

{/foreach}

</xml>

Weitere Definitionen finden sich auch den Dokumentation von Smarty zu Scheifen am Bespiel 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->number}"

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

"warehouse":"{$st->short description}"

},



{if $st@last}

{

"materialId":"{$st->number}"

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

"warehouse":"{$st->short description}"

}

{/if}

{/foreach}

]}

Smarty im Übertragen-Modul

Das Übertragen-Modul ermöglicht es eine Vielzahl von Belegen oder Daten aus '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} 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,

  • Funktionen (wie z.B. truncate) bearbeitet,

  • 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 '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} interne Format zur Verarbeitung (in den meisten Fällen '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} XML).

Smarty Ausgehend (outbound oder Export)

Daten aus '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} zu versenden (auch “outbound” genannt) ermöglicht es die Daten von '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"}

  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"?>

<order>

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

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

<delivery date>{$voucher->delivery_date}</delivery_date>

<shipping method>{$voucher->shipping method}</shipping method>

<payment method>{$voucher->payment method}</payment method>

<document number>{$document->document number}</document number>

<customer number>{$voucher->customer number}</customer number>

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

<street>{$claim->street}</street>

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

<location>{$document->location}</location>

<items>

{foreach from=$voucher->positions key=keyrow item=position}{* positions *}

 <position>

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

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

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

 <quantity>{$item->quantity}</quantity>

 <price>{$item->price}</price>

 <unit>{$item->unit}</unit>

</position>

{/foreach}

</positions>

{if $voucher->shipping}

 <tracking>

 {foreach from=$voucher->shipping key=keyshipping item=tracking}{* shipping *}

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

 {/foreach}

 </tracking>

{/if}

</order>

Smarty Eingehend (inbound oder Import)

Daten in '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} einzulesen (auch “inbound” genannt) ermöglicht es die Daten

  1. aus einem anderen System zu importieren,

  2. zu interpretieren, dann

  3. in ein '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} Zielformat zu konvertieren und anschließend

  4. in '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"} 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-&gt;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