Documented new attachment token with CSV example and restructured examples

Author: Toflar

docs/notification-center-pro/custom-tokens/_index.de.md

@@ -6,7 +6,8 @@ weight: 200
 
 Mit dem Notification Center Pro kannst du benutzerdefinierte Tokens erstellen, die du dann in deinen Benachrichtigungen verwenden kannst. Eigene Tokens basieren auf Twig-Templates, d.h. du kannst von allen Twig-Funktionen profitieren, die du dir vom Contao-Templating gewohnt bist.
 
-Da die Möglichkeiten praktisch endlos sind, sehen wir uns ein Beispiel an. Du kannst auch einen Blick auf unsere [Beispielsammlung]({{% ref "/custom-tokens/example-collection" %}}) werfen, in der wir gängige Anwendungsfälle sammeln. Wenn du etwas hast, von dem du denkst, dass andere es verwenden könnten, lass es uns bitte wissen!
+Da die Möglichkeiten praktisch endlos sind, sehen wir uns ein Beispiel an. Du kannst auch einen Blick auf unsere 
+[Beispielsammlung]({{% ref "/custom-tokens/examples" %}}) werfen, in der wir gängige Anwendungsfälle sammeln. Wenn du etwas hast, von dem du denkst, dass andere es verwenden könnten, lass es uns bitte wissen!
 
 ## Beispiel Anwendungsfall
 

docs/notification-center-pro/custom-tokens/_index.en.md

@@ -7,7 +7,8 @@ With Notification Center Pro, you can create custom tokens which you can then us
 tokens are based on Twig templates which means you can access all the goodness you know and love from Contao 
 templating.
 
-As the possibilities are virtually endless, let's look at an example. You can also take a look at our [example collection]({{% ref "/custom-tokens/example-collection" %}}) where we collect common use cases. If you have something you think other users could use, please let us know!
+As the possibilities are virtually endless, let's look at an example. You can also take a look at our [example 
+collection]({{% ref "/custom-tokens/examples" %}}) where we collect common use cases. If you have something you think other users could use, please let us know!
 
 ## Example use case
 

docs/notification-center-pro/custom-tokens/example-collection/_index.de.md

@@ -0,0 +1,9 @@
+---
+title: "Beispiele"
+url: "eigene-tokens/beispiele"
+weight: 20
+---
+
+Hier findest du eine Samlung von Beispielen anderer Anwender:innen. Wenn du auch ein tolles Beispiel hast, das du gerne hier aufgelistet hättest, lass es uns bitte wissen!
+
+{{% children %}}

docs/notification-center-pro/custom-tokens/example-collection/_index.en.md

@@ -0,0 +1,8 @@
+---
+title: "Examples"
+weight: 20
+---
+
+Here you can find a collection of examples from other users. If you also have a great example that you would like to see listed here, please let us know!
+
+{{% children %}}

docs/notification-center-pro/custom-tokens/examples/_index.de.md

@@ -0,0 +1,42 @@
+---
+title: "Rechnen mit Twig"
+url: "eigene-tokens/beispiele/rechnen-mit-twig"
+---
+
+Kennst du das? Ein einfaches Bestellformular, ohne grosse Webshop-Implementierung aber trotzdem hättest du gerne die 
+MwSt. und das Total in der E-Mail ausgewiesen? Mit dem Notification Center Pro absolut kein Problem, wir können uns 
+ja eigene Tokens für die MwSt. und das Total erstellen und diese dann nutzen. Wir nehmen an, wir haben ein Formularfeld, das heisst `anzahl_prospekte` und dort kann man als Besteller:in Prospekte bestellen. Jeder Prospekt kostet 4 Euro. Wenn jetzt jemand 5 Prospekte bestellt, möchten wir also eine Mail mit 20 Euro plus 3.80 Euro MwSt (19% in diesem Beispiel) und einem Gesamt-Total von 23.80 Euro schicken.
+
+In unsere Mail schreiben wir bspw. Folgendes:
+
+```none
+Hallo ##form_firstname##,
+
+Du hast bei uns ##form_anzahl_prospekte## Prospekte bestellt. Hier ist deine Rechnung:
+
+##form_anzahl_prospekte## Prospekte à € 4,-: ##subtotal##
+Mehrwertsteuer 19%: ##mwst##
+Gesamttotal: ##gesamttotal##
+```
+
+So könnte unsere Twig-Logik dann aussehen:
+
+```twig
+{% if rawTokens.has('form_anzahl_prospekte') %}
+{% set subtotal = rawTokens.byName('form_anzahl_prospekte').value * 4 %}
+{% set mwst = subtotal * 19 / 100 %}
+{% set gesamttotal = subtotal + mwst %}
+{% endif %}
+```
+
+Diese Logik kopieren wir nun in 3 Tokens und geben jeweils die gewünschte Variable aus:
+
+1. Token `subtotal` nutzt obengenannte Logik und `{{ subtotal }}`
+2. Token `mwst` nutzt obengenannte Logik und `{{ mwst }}`
+3. Token `gesamttotal` nutzt obengenannte Logik und `{{ gesamttotal }}`
+
+Tada! 🎉
+
+{{% notice tip %}}
+Verwende den [Twig-Filter `number_format`](https://twig.symfony.com/doc/3.x/filters/number_format.html), um die Zahlen nach deinen Wünschen zu formatieren!
+{{% /notice %}}

docs/notification-center-pro/custom-tokens/examples/_index.en.md

@@ -0,0 +1,44 @@
+---
+title: "Calculating with Twig"
+---
+
+Do you know this situation? A simple order form, without a large webshop implementation, but you would still like to 
+have the VAT and the total shown in the e-mail? No problem at all with the Notification Center Pro, we can create our own tokens for the VAT and the total and then use them. Let's assume we have a form field called `number_of_brochures` where the customer can brochures. Each brochure costs 4 Euros. If someone now orders 5 brochures, we would like to send a mail with 20 Euro plus 3.80 Euro VAT (19% for Germany in this example) and a total amount of 23.80 Euro.
+
+For example, we write the following in our mail:
+
+```none
+Hello ##form_firstname##,
+
+You have ordered ##form_number_of_brochures## brochures from us. Here is your invoice:
+
+##form_number_of_brochures## brochures at € 4,- each: ##subtotal##
+Value added tax 19%: ##tax##
+Total amount: ##total##
+```
+
+So könnte unsere Twig-Logik könnte dann wie folgt aussehen:
+
+```twig
+{% if rawTokens.has('form_anzahl_prospekte') %}
+{% set subtotal = rawTokens.byName('form_number_of_brochures').value * 4 %}
+{% set tax = subtotal * 19 / 100 %}
+{% set total = subtotal + tax %}
+{% endif %}
+```
+
+We now copy this logic into 3 tokens and output the desired variable in each case:
+
+1. token `subtotal` uses the above logic and `{{ subtotal }}`
+2. token `tax` uses the above logic and `{{ tax }}`
+3. token `total` uses the above logic and `{{ total }}`
+
+Tada! 🎉
+
+{{% notice tip %}}
+Use the [Twig `number_format` filter](https://twig.symfony.com/doc/3.x/filters/number_format.html) to format the numbers to your liking!
+{{% /notice %}}
+
+
+
+

docs/notification-center-pro/custom-tokens/examples/calculating-with-twig.de.md

@@ -0,0 +1,69 @@
+---
+title: "CSV-Anhang"
+url: "eigene-tokens/beispiele/csv-anhang"
+---
+
+Stell dir vor, du möchtest eine CSV-Datei an deine E-Mail anhängen, die die eingegebenen Formulardaten enthält.
+Das Hauptproblem, das du dabei beachten musst, ist das korrekte Escaping. Stell dir eine Logik wie diese vor:
+
+```
+firstname,lastname,city
+##form_firstname##,##form_firstname##,##form_city##
+```
+
+Das würde nicht funktionieren, indem du einfach die Tokens ersetzt, weil du drei verschiedene Zeichen escapen musst:
+
+* Das Trennzeichen ("Delimiter" - `,` standardmässig)
+* Das Begrenzungszeichen ("Enclosure" - `"` standardmässig)
+* Das Escape-Zeichen selbst (`\` standardmässig)
+
+Andernfalls, wenn ein Besucher z. B. `Jürgen "Kloppo"` als Vornamen und `Portland, ME` als Stadt angibt, um zu 
+präzisieren, welches Portland gemeint ist, würdest du am Ende etwas erhalten, das völlig ungültiges CSV ist:
+
+```
+firstname,lastname,city
+Jürgen "Kloppo",Klopp,Portland, ME
+```
+
+Die korrekte Ausgabe wäre:
+
+```
+firstname,lastname,city
+"Jürgen \"Kloppo\"",Klopp,"Portland, ME"
+```
+
+Das manuell zu tun ist schwierig, deswegen verfügt das Notification Center Pro über einen `csv` Twig-Filter:
+
+```twig
+{% set headers = [
+    'firstname', 
+    'lastname',
+    'city',
+] %}
+{{ headers|csv }}
+{% set row = [
+    parsedTokens.form_firstname|default(''), 
+    parsedTokens.form_lastname|default(''), 
+    parsedTokens.form_city|default(''), 
+] %}
+{{ row|csv }}
+```
+
+{{% notice tip %}}
+Der [Twig `default`-Filter](https://twig.symfony.com/doc/3.x/filters/default.html) sorgt dafür, dass statt eines 
+Fehlers eine leere Ausgabe erfolgt, wenn ein Token nicht existiert.
+{{% /notice %}}
+
+Das war's! Du hast nun ein Token mit dem korrekten CSV-Wert. Alles, was du noch tun musst, ist diesem Token einen 
+Namen zu geben, es als Datei-Token zu aktivieren und ihm den gewünschten Dateinamen zu vergeben:
+
+![Screenshot of the file attachment token configuration]({{% asset "/notification-center-pro/images/screenshot_csv_token_attachment.png" %}}?classes=shadow)
+
+Dieses Token kann nun benutzt werden, um bspw. das CSV einer Mail anzuhängen. Tada! 🎉
+
+{{% notice tip %}}
+Der `csv`-Filter ist nicht Teil von Twig, sondern wird stattdessen vom Notification Center Pro bereitgestellt. Du 
+kannst auch mit einem anderen Trennzeichen arbeiten. Wenn du die Werte beispielsweise mit `;` trennen möchtest, 
+verwende `{{ row|csv(';') }}`. Der zweite und dritte Parameter können genutzt werden, um das "Enclosure" und 
+Escape-Zeichen entsprechend anzupassen, falls erforderlich.
+{{% /notice %}}

docs/notification-center-pro/custom-tokens/examples/calculating-with-twig.en.md

@@ -0,0 +1,67 @@
+---
+title: "CSV attachment"
+---
+
+Imagine you wanted to attach a CSV file to your e-mail that contains the form data that was submitted.
+The major problem here you need to consider is correct escaping. Imagine a logic like this:
+
+```
+firstname,lastname,city
+##form_firstname##,##form_firstname##,##form_city##
+```
+
+This would not work by simply replacing the tokens because you need to escape 3 different characters:
+
+* The separator (`,` by default)
+* The enclosure (`"` by default)
+* The escape character itself (`\` by default)
+
+Otherwise, if a visitor e.g. submits `Jürgen "Kloppo"` as their firstname and `Portland, ME` as city to clarify which 
+Portland, you would end up having this which is completely invalid CSV:
+
+```
+firstname,lastname,city
+Jürgen "Kloppo",Klopp,Portland, ME
+```
+
+The correct output would be
+
+```
+firstname,lastname,city
+"Jürgen \"Kloppo\"",Klopp,"Portland, ME"
+```
+
+Doing that manually is hard, this is why the Notification Center Pro provides its own `csv` Twig filter:
+
+```twig
+{% set headers = [
+    'firstname', 
+    'lastname',
+    'city',
+] %}
+{{ headers|csv }}
+{% set row = [
+    parsedTokens.form_firstname|default(''), 
+    parsedTokens.form_lastname|default(''), 
+    parsedTokens.form_city|default(''), 
+] %}
+{{ row|csv }}
+```
+
+{{% notice tip %}}
+The [Twig `default` filter](https://twig.symfony.com/doc/3.x/filters/default.html) would make sure there is an empty 
+value if the token is not provided instead of throwing an error.
+{{% /notice %}}
+
+That's it, you now have a token with the correct CSV value. All you need to do is to give this token a name, enable 
+it as a file token and give it your desired filename:
+
+![Screenshot of the file attachment token configuration]({{% asset "/notification-center-pro/images/screenshot_csv_token_attachment.png" %}}?classes=shadow)
+
+This token can now be used to e.g. attach it to an e-mail. Tada! 🎉
+
+{{% notice tip %}}
+The `csv` filter is not part of Twig but instead provided by the Notification Center Pro. You can also work with a 
+different delimiter. If you need to separate the values by `;` for example, use `{{ row|csv(';') }}`. The second and 
+third argument can be used to configure the enclosure and escape character respectively, if required.
+{{% /notice %}}