Smarty is a technology that makes it possible to convert data quickly and clearly. The following applies: All text-based formats can be converted, regardless of whether they are CSV, XML, JSON or otherwise structured files.
Smarty can be used in various places in Xentral
-
Smarty in the Transfer module
-
Smarty in store interfaces
The available functions and associated modifiers are largely identical. We therefore point out special features in the corresponding sections of the documentation. Smarty is already included in Xentral at the appropriate places. Downloading libraries is not necessary.
The basis of the conversion is always the so-called Smarty Template. It defines the format and structure of the outgoing document. For this purpose, the target format can simply be copied into the template editor in the form of a sample file. Then the sample data is replaced by variables and can be filled by the system.
Using the example of an order as an XML file, it is shown here how this conversion can take place.
The following format should be output:
<?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>
This sample file is copied into the template editor. Then the sample values are replaced with the associated variables.
<?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>
Depending on the area, a base object is used to access the values. Depending on the area of application, this is a different object:
-
$voucher → Used in the transfer module to process outgoing voucher data.
-
$articlelist → Used in the commit module to process outgoing items or stock levels. (stock numbers)
-
$trackinglist → Transmit module - Process outgoing tracking information
-
$salesreportlist → Transfer Module - Process Outgoing Document Data
-
$object → Incoming data is processed in the Transfer module
-
$cart → used in the store interface to process the shopping cart
All examples described here are from the standard scope of the used template engine Smarty. Further functions can therefore be found in the official Smarty documentation: https://www.smarty.net/docs/en/language.modifiers.tpl
Number is to be shortened to 3 decimal places. Then the point is to be replaced by a comma. Instead of a number, a variable or the result of a calculation can be used.
Template:
{1.12345|string_format:"%1\$.3f"|replace:".":","}
Result: 1.123
Further definitions can also be found in the documentation of the Smarty modifier string_format.
For example, if a long text value for the name (order => name =>) "Max Mustermann" should be imported in the shopping cart, it could also be shortened to a fixed text length (in characters) using Smarty.
Template:
{$cart->order->name|truncate:6}
Result: Max...
Further definitions can also be found in the documentation of the Smarty modifier truncate
With the help of conditions, logic can already be worked with in the template in order to transfer customer-specific decisions into different results during the export or import of data.
In the following example, when importing an order via a store interface, the English value "mr" is converted to the salutation "herr", which in Xentral stands for the address type and the salutation "Mr".
Example Shopimporter:
<xml>
<name>Max Mustermann</name>
{if $cart->order->salutation == "mr"}
<salutation>mr</salutation>
{else}
<address>woman</address>
{/if}
</xml>
Alternative spelling (Shopimporter)
<xml>
<name>Max Mustermann</name>
<salutation>
{if $cart->order->salutation == "mr"}
mr{else}wife{/if}
</address>
</xml>
Another alternative notation for overwriting a node (store importer)
<xml>
<name>Max Mustermann</name>
<salutation>wife</salutation>
{if $cart->order->salutation == "mr"}
<address>gentleman</address>
{/if}
</xml>
In this example, the second node with the same name (title) overwrites the complete first node incl. value if the condition is true and thus replaces the content.
Further definitions can also be found in the Documentation of the Smarty if/else
Loops allow the processing of value lists (arrays), e.g. order items, tax rates, or similar. The results are usually key-value pairs, which can then be evaluated in a second step. For this purpose, these lists are run through and processed in a loop.
In the following example, for a given structure of the billing address, any element is picked out to set a separate setting for the country, for example.
Example Shopimporter
Shopping cart:
...
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>
Further definitions can also be found in the documentation of Smarty on loops using the example foreach
Especially when outputting JSON or XML lists it can be important to terminate the list element cleanly. To get invalid data structures, all elements that are not at the end of the list must be terminated with a comma. For this purpose the syntax $item@last can be used.
Example
Output of a JSON file with the article inventory
{"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}
]}
The Transfer module allows to export a variety of documents or data from Xentral. In addition to various output formats and output channels, various triggers are offered for export (e.g. the document status, label, ID or date of a document, etc.). The Smarty Transfer module is used for this purpose.
With the help of Smarty the target format of the output data can now be defined by yourself and with the help of
-
functions (such as truncate),
-
enriched with SQL queries
-
and by using loops, conditions or similar with logic
be changed.
In the Transmit module, Smarty is available for incoming and outgoing messages. Here the template determines
-
for outgoing messages, the target format expected by the remote station
-
for incoming messages, the Xentral internal format for processing (Xentral XML in most cases).
Sending data from Xentral (also called "outbound") allows the data from Xentral to be
-
convert to a target format and then
-
export to a third-party system.
A template file could look like this, for example:
<?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>
Reading data into Xentral (also called "inbound") enables the data to be
-
imported from another system,
-
to interpret, then
-
convert to a Xentral target format and then
-
to import into Xentral.
In all documents, linked documents can be accessed with the help of Smarty. If, for example, a delivery bill exists for an order, an array $beleg->lieferschein[] also exists in which the corresponding information of the referenced delivery bill is then available. In this way, supplementary document numbers, delivery data, batches or serial numbers can be quickly accessed - even when creating an order. The delivery note number, for example, would be directly accessible via $document->delivery bill[0]->document no.
The following data is available in the respective documents, provided that a corresponding document exists in the system.
By order of:
-
$voucher->order[]
-
$quote->quote[]
-
$document->delivery bill[]
-
$voucher->invoice[]
-
$beleg->retoure[]
-
$voucher->credit[]
In the delivery bill:
-
$voucher->order[]
-
$voucher->invoice[]
In the bill:
-
$voucher->order[]
-
$document->delivery bill[]
In the Transfer module, general SQL queries can also be created to enrich data and output in the output templates. The following syntax is used for this purpose:
{"SELECT gln, rechnung_gln FROM adresse where lieferantennummer =
'{$beleg->lieferantennummer}' "|assignsql assign="adressdata"}
The result can then be accessed via the assigned array addressdata:
{$adressdata[0]->gln} // für den gezielten Aufruf des Arrays