Skip to main content

Smarty Introduction

  • Updated

Smarty is a technology that allows you to convert data quickly and clearly. You can convert all text-based formats, no matter if they are CSV, XML, JSON or other structured files.

You can use Smarty in several places in Xentral:

  • Smarty in the Transfer module

  • Smarty in store interfaces

The available functions and corresponding modifiers are mostly identical. Therefore, we 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.

Procedure

The basis of the conversion is always the so-called Smarty Template. It defines the format and structure of the outgoing document. To do this, you can simply copy the target format in the form of a sample file into the template editor. Then the sample data is replaced by variables and can be filled by the system.

Using the example of a job as an XML file, here is an illustration of how this conversion can take place.

The following format is to be output:

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

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

Depending on the area, a base object is used to access the values. Depending on the area of use, this is a different object:

  • $voucher → Transfer module: Process outgoing document data

  • $articlelist → Transfer module: Process outgoing items or stock (stock numbers)

  • $trackinglist → Transfer module: Process outgoing tracking information

  • $salesreportlist → Transfer module: Process outgoing document data

  • $object → Transfer module: Process incoming data

  • $cart → Shop interface: Process shopping cart

Functions and modifiers

Most of the examples described here come from the standard scope of the used template engine Smarty. You can find more functions in the official Smarty documentation.

Basically, functions or modifiers are written after the pipe character ( | ) in the variable, possibly with subsequent parameters, separated by a colon.

Template: { value or $variable | modifier or function: more parameters }

Examples

The following script shows you an example of how to use Smarty with constants, value assignments, variables, functions and modifiers. Some of them are described in more detail below.

<xml>

{* 0. Statisch *}
<auftragsdaten></auftragsdaten>
<transactions/>
<anrede>herr</anrede>

{* 1. Wertzuweisung *}
<waehrung>{$cart->auftragsdaten->currency}</waehrung>

{* 2. Rechnen *}
<gesamtsumme>{($cart->auftragsdaten->total_price - 5)}</gesamtsumme>

{* 3. Variablenzuweisung *}
{assign var=data value=$cart->auftragsdaten}
<email>{$data->email}</email>

{* 4. Funktionen *}
<bestelldatum>{$cart->auftragsdaten->processed_at|truncate:10:''}</bestelldatum>

{* 5. Verzweigungen *}
{if $cart->auftragsdaten->total_tip_received > 0}
 <freitext>Danke für die Spende von {$cart->auftragsdaten->total_tip_received} {$cart->auftragsdaten->currency}!!!</freitext>
{else}
 <freitext>Geiz ist geil!</freitext>
{/if}

{* 6. Schleifen *}
{foreach key=key item=item from=$cart->auftragsdaten->note_attributes}
  {if $item->name == "google-clientID"}
<internebemerkung>Google ClientID: {$item->value}</internebemerkung>
  {/if}
{/foreach}
</xml>

Script functions

Assign variables and contents

The assign command can be used to create variables and assign values to them. This can be used to simplify readability in the template.

Template:

{assign var=order value=$cart->auftragsdaten}

Result: The value of $cart->auftragsdaten->datum is shortened to $order->datum.

For more definitions, see the documentation of the Smarty assign function.

Number editing

Here you will learn how to edit numbers.

Truncate decimal places

A number is to be shortened to three decimal places. Then the point is to be replaced by a comma. Instead of a number, it can of course also be a variable or the result of a calculation.

Template:

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

Result: 1,123

For more definitions, see the documentation of the Smarty modifier string_format.

Simple calculations

In addition to more complex calculations, you can also perform simple calculations directly in the output of the variable. All you have to do is put a parenthesis () around the expression.

Template:

{($cart->versandkostenbrutto-0.95)}

Result: Output of the residual value, e.g. at <versandkostenbrutto>4,95</versandkostenbrutto> = 4

Text editing

Here you will learn how to edit texts.

Limit text length

For example, if a long text value for the name (order => name =>) "Max Mustermann" is imported in the shopping cart, it could also be shortened to a fixed text length (in characters) using Smarty.

Template:

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

Result: Max

or:

{$cart->order->name|truncate:3,””}

Result: Max

You can find more definitions in the documentation of the Smarty modifier truncate.

Alternatively, you can also work with the help of string formatting:

Template:

{$cart->order->name|string_format:"%s{3}"}

You can find more definitions in the documentation of the Smarty modifier string_format

Clean up text ends

Replaces multiple spaces, line breaks, and tabs in the variable's contents with a space or an alternate string (in the second example &nbsp;).

Template:

{$cart->order->name|strip}

or

{$cart->order->name|strip:&nbsp;}

You can find more definitions in the documentation of the Smarty Modifier strip.

Search and replace text

Template:

{$original|replace:“foo":“bar”|getxml assign=“newxml”}

Replaces all strings foo to bar and saves/converts it to a new object $newxml.

Find and replace text with regular expression

Template:

{$position->nummer|pregreplace:‘/[^0-9]/‘:’’}

Performs a regular replacement on the element.

For more definitions, see the documentation of the Smarty modifier regex/replace.

Error handling/logging

Here you can learn how to create log entries.

Logging in the commit module

template:

{“Der Auftrag enthält keine Positionen”|error}

Outputs an error to Smarty, which is logged and output in the monitor of the transfer module.

Data output

Template:

{$orderData|@debug_print_var}

Outputs the data of the preceding element in the Output window.

Conditions

With the help of conditions, logic can already be used in the template to convert customer-specific decisions into different results already when exporting or importing data.

In the following example, when importing an order via a store interface, the English value "mr" is converted into the salutation "herr", which in xentral stands for the address type and the salutation "Herr".

Example Shopimporter:

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

Alternative notation (Shopimporter)

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

Another alternative notation for overwriting a node ( Shopimporter)

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

In this example the second node with the same name (anrede) overwrites the complete first node including the value if the condition is true and replaces the content.

Further definitions can be found in the Smarty if/else documentation.

Loops

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, an arbitrary element is picked out, e.g. to set a separate setting for the country.

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”}
      <land>{$billingData->value}</land>
    {/if}
  {/foreach}
</xml>

For more definitions, see Smarty's documentation on loops using foreach as an example.

Tips and tricks

Here you can find some tips and tricks that might help you.

Escaping strings with CDATA

A lot of data that can be transmitted or read in Smarty contains characters that can be misinterpreted by further processing. Therefore it is important to distinguish the transmitted content from the structural data. To do this, you can enclose the data by a CDATA block and thus "escape" it.

Template:

<![CDATA[{$orderData->total_price}]]>

More information about CDATA and its usage.

Last element of a loop

Especially when outputting JSON or XML lists, it can be important to terminate the list element cleanly. To get invalid data structures, you need to terminate all elements with a comma that are not at the end of the list. You can use the $item@last syntax to do this.

Example

Output a JSON file with the item inventory:

{"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}
]}

Related articles

Visit the Academy - you'll find videos for most topics