VHS1TwigToolkit
Info
Kompatibel mit VHS1 ab Version 2020.1929
.
Installation, Konfiguration & Verwendung
Nach dem klonen des Repositories muss die Standard Konfiguration auf die entsprechende VHS1-Instanz konfiguriert werden. Dazu einfach die Konfiguration-Vorlage kopieren und anpassen.
$ cp src/Config/config.json.dist src/Config/config.json
Die Basiskonfiguration benötigt die folgenden Daten:
- Url, Rest-API-Anwendungs-Url
- Client
- Api Key
Im Anschluss müssen die entsprechenden Templates eingebunden werden. Die generelle Struktur sieht in der Regel so aus:
src/Templates/email
src/Templates/image
src/Templates/slip
Templates können entweder in src/Templates
kopiert, oder gelinkt werden. Wenn du die Templates "symlinken" willst, musst
du den Pfad zu den Templates mit in den Container mounten.
Zunächst müssen wir aber, so oder so, die Vorlage der docker-compose.yml.dist
kopieren:
$ cp docker-compose.yml.dist docker-compose.yml
Die docker-compose.yml
Datei wird absichtlich ignoriert von git
, nämlich, wie oben erwähnt, wenn man die Templates per
Symlink einbinden will, diese Datei sonst immer als modifiziert auftauchen würde.
Um Symlinks zu nutzen, können wir einfach in der docker-compose.yml
einen weiteren Eintrag
unter volumes
hinzufügen, z.B. so:
- '/home/benutzer/workspace/template:/home/benutzer/workspace/template'
Nun steht der Symlink-Pfad /home/benutzer/workspace/template
im Container zur Verfuegung und es können folgende Symlinks aufgelöst werden.
- 'email -> /home/benutzer/workspace/templateRepo/email'
- 'slip -> /home/benutzer/workspace/templateRepo/slip'
- 'image -> /home/benutzer/workspace/templateRepo/image'
Dazu wie folgt vorgehen:
$ cd src/Templates
$ ln -s /absolute/path/to/templates-repo/email/
$ ln -s /absolute/path/to/templates-repo/slip/
$ ln -s /absolute/path/to/templates-repo/image/
Sollte ein Projekt von dieser Struktur abweichen, können die Pfade in folgender
Datei angepasst werden: src/Service/TwigService.php
Im Anschluss den Container starten (der erste Start führt die Erstellung des Containers durch, dass kann einige Zeit dauern.)
$ docker-compose up -d
Nach der Installation kann die Anwendung folgendermaßen erreicht werden:
http://localhost:8085
Oben auf der Seite sehen wir nun eine Toolbar. Über diese können wir bequem die Informationen angeben, die die Anwendung benötigt. Art (Im Moment nur Dokument, keine E-Mails), den Typen, das Template und den Identifier. Dies sind sind Pflichtfelder. Zusätzlich können wir noch ein Werbemittel angeben und steuern, ob die Daten aus dem lokalen Cache geladen, oder aktualisiert werden sollen.
Nach Absenden des Formulars, wird ein iFrame erzeugt welches folgende Route aufruft:
http://localhost:8085/{kind}/{type}/{template}/{identifiers}/{advertisingMediumCode}?forceReload={bool}
Ein Beispiel für eine (gecachte) Rechnung würde so aussehen:
http://localhost:8085/pdf/invoice/default_invoice.html/{Rechnungsnummer}
Wenn wir also möchten, können wir auch direkt die URL aus dem iFrame aufrufen.
Je nach ausgewähltem Typen, sind die Identifier unterschiedlich. Rechnungsnummer bei Typ 'invoice', Picklistennummer bei Typ 'picklist' etc.
Hat das angeprochene System eine höhere Buildnummer als 1930
, werden sich die Typen über eine API des VHS geholt. In allen anderen Fällen,
werden auf statisch hinterlegte Werte zurückgegriffen.
Hat das angesprochene System eine höhere Buildnummer als 1931
, werden sich zusätzlich noch die verfügbaren Sprachen des System geholt und
in einem Dropdown auf der Seite angezeigt. Mit der zusätzlichen Sprachauswahl, können so die Templates mit verschiedenen Sprachen getestet werden.
Denn bei einer angegebenen Sprache werden die Textbausteine, sofern vorganend, übermittelt.
Bedienen
Um eine Vorschau der angepassten Templates zu sehen, müssen wir dem Tool mitteilen, was wir bearbeiten möchte und woher die Daten genommen werden sollen.
Zunächst wählen wir also eine Art
aus. Hier werden PDF
und E-Mail
unterstützt. Je nach ausgewählter Art, werden die verfügbaren Typen
geladen.
Im nächsten Schritt müssen wir den Namen des Templates angeben, welches für die Darstellung genommen werden soll. Dann müssen wir eine Identifikation
angeben.
Diese ist abhängig von dem ausgewählten Typen
, also für eine Rechnung
brauchen wir beispielsweise eine Rechnungsnummer
. Weiter unten ist eine Liste zur Hilfe.
Diese vier Felder Art
, Typ
, Template
und Identifikation
sind Pflichtfelder.
Die Produkt ID muss bei einigen Templates
(E-Mail) zusätzlich angegeben werden. Siehe dazu wieder weiter unten die Liste.
Das Werbemittel ist auch optional und kann angegebeben werden. Z.B.: wenn wir "dynamische" Anzeigen im Template auf Basis des Werbemittels haben, oder bestimmte Werte der Textbausteine an ein Werbemittel gebunden sind.
Mit der Sprache verhält es sich ähnlich wie mit den Werbemitteln. Die verfügbaren Sprachen werden automatisch geladen und beeinflusst die angezeigte Spreche - logisch.
Art | Typ | Template (kann abweichen) | Identifikation | Produkt ID (ja/nein) |
---|---|---|---|---|
Rechnung | default_invoice.html | Rechnungsnummer | ||
Rechnungs (Email-Anhang) | default_invoice_email.html | Rechnungsnummer | ||
Retourenschein | default_return_slip.html | Rechnungsnummer | ||
Lieferschein | default_delivery_slip.html | Rechnungsnummer | ||
Pickliste | default_pick_list.html | Picklistennummer | ||
Nachfüllauftrag | default_stock_relocation.html | Nachfüllauftragsnummer | ||
Umlagerungsauftrag | default_relocation.html | Umlagerungsnummer | ||
Mahnung | default_motion_slip.html | ID der Mahnung | ||
Lieferantenbegleitdokument | default_supply_note.html | Lieferantenbestellnummer | ||
Lieferantenbestellung | default_supplier_order_slip.html | Lieferantenbestellnummer | ||
Anschreiben Herstellerreparatur | default_repair_case_cover_letter.html | Reparaturfallnummer | ||
Reparatur-Lieferschein | default_repair_case_return_form.html | Reparaturfallnummer | ||
Auftragsbestätigung | default_order_confirmation.html | Bestellnummer | ||
Angebot | default_offer.html | Bestellnummer | ||
Produkt-Etikett | default_label_small/big.html | Identifikation (z.B. EAN, Artikelnummer) | ||
Lagerfach-Etikett | default_tray_label.html | Lagerfachcode | ||
Benutzerausweis | default_user_id_card.html | ID des Benutzers | ||
PickBox-Etikett | default_pick_box.html | Pickboxnummer/Identifikation | ||
POS - Abschluss | default_pos_report.html | ID des Reports | ||
Inventurbeleg | default_stock_inventory.html | Inventurnummer | ||
Lieferantenbestellung | default_supplier_order.html | Lieferantenbestellnummer | ||
Lieferantenbestellung Bestelländerung | default_supplier_order_changed.html | Lieferantenbestellnummer | ||
Lieferantenbestellung Mahnung | default_supplier_order_reminder.html | Lieferantenbestellnummer | ||
Lieferantenbestellung Stornierung | default_supplier_order_cancel.html | Lieferantenbestellnummer | ||
Lieferantenbestellung Abschluss | default_supplier_order_finished.html | Lieferantenbestellnummer | ||
Lieferverzugsemail | default_order_delivery_delay.html | ID der Bestellzeile | ||
Bestelleingang | default_order_received.html | Bestellnummer | x | |
Mahnung | default_monition.html | ID der Mahnung | ||
Rechnungsversand | default_email_invoice.html | Bestellnummer | ||
Rechnungsversand (Buchhaltung) | default_accountancy_invoice_email.html | Bestellnummer | x | |
Bestelländerung | default_order_changed.html | Bestellnummer | x | |
Bestellstornierung | default_order_canceled.html | Bestellnummer | x | |
Bestellung Logistikanmeldung | default_order_moved_to_logistic.html | Bestellnummer | x | |
Versandbestätigung | default_order_shipped.html | Versandauftragsnummer | ||
Lastschriftavis | default_order_payment_advise.html | EREF (End2End Reference) | x | |
Zahlungseingang | default_payment_cleared.html | Bestellnummer | x | |
Retoureneingang | default_incoming_return.html | Retourennummer | ||
Zahlungseingang (Bankkonto) | default_payment_cash_cleared.html | Bestellnummer | x | |
Vorkasse-Erinnerung | default_pre_payment_reminder.html | Bestellnummer | x | |
Retourenverarbeitung | default_return_processed.html | Retourennummer | ||
Retoureninformationen | default_order_return_info.html | Bestellnummer | ||
Produkt NLB | default_order_product_nlb.html | Bestellnummer | x | |
Selbstabholerbenachrichtigung | default_order_ready_for_collection.html | Bestellnummer | x | |
Kommissionierungshinweis | default_order_in_picking.html | Bestellnummer | x | |
Streckengeschäft | default_drop_shipment_order.html | Bestellnummer | x | |
Streckengeschäft Zuweisung Lieferant | Lieferantenbestellnummer | |||
Streckengeschäft Kundenbenachrichtigung | Versandauftragsnummer |
Context überschreiben
Es ist möglich in der Konfigurationsdatei src/Config/config.json
sämtliche Werte des Kontextes zu überschreiben.
Dies kann erreicht werden unterhalb des Knotens: mapping -> defaults
, aber hier muss der Aufbau des Kontextes
nachgebaut werden, um die gewünschten Werte zu überschreiben.
Also z.B. den Bildpfad des Box-Barcodes: mapping -> defaults -> invoice -> boxBarcode
.
Ein vollständiges Beispiel befindet sich in der src/Config/config.json.dist
Datei.
Textbausteine
Die Textbausteine können ähnlich überschrieben werden, wie die Werte des Kontextes. Dazu einfach die gewünschten Textbausteine
samt Übersetzung (Key/Value) in folgenden Knoten der src/Config/config.json
einfügen: mapping -> textModuleMapping -> defaults
.
Möchte man Übersetzungen pro Werbemittel anlegen, kann ein weiterer Knoten, auf derselben Ebene, wie die defaults
hinzugefügt werden.
Also beispielsweise: mapping -> textModuleMapping -> ABC
. Diese Werte pro Werbemittelcode können dann, sofern vorhanden in den Defaults,
Werte überschreiben. D.h. man kann in den Defaults Standardwerte eintragen und diese dann individuell für jedes Werbemittel einzeln, oder alle (defaults
) überschreiben.
Weiter kann man auch die defaults
für eine bestimmte Sprache überschreiben, dazu beispielsweise einen Knoten mapping -> textModuleMapping -> defaults-en
hinzufügen. Also
an das Werbemittel, oder eben den Defaults, ein -LANGUAGE_CODE
anhängen.
Leere Bausteine, also ohne Übersetzung, werden mit ihrem "Schlüssel" im PDF angezeigt. Ebenso Bausteine für die es keinen Eintrag
in der Konfiguration gibt.
Ist dieses Verhalten nicht gewünscht, kann man den Code in src/Twig/Loader/TextModuleLoader.php
anpassen.
Cache
Folgende Daten werden lokal auf dem Filesystem gespeichert:
- JWT
- der Kontext
- die Textbausteine
- VHS Buildnummer
- Typen
- Sprachen
Der JWT
wird, da er für 8 Stunden gültig ist, für 8 Stunden auf der Platte gespeichert. Wird der JWT
aus dem Cache
gelöscht, dann wird sich automatisch ein neuer geholt.
Der Kontext eines jeden Typs + Identifier wird ebenso auf der Festplatte gespeichert. Hier muss man aufpassen: Einmal im Cache,
kann der Kontext nur aktualisiert werden, wenn man den Cache leeren
Button benutzt. Dann wird der Cache geleert und die Seite frisch
geladen. Alternativ kann man auch den Cache manuell aus dem Dateisystem löschen: rm -rf /tmp/smyfony-cache
.
Ähnlich verhält es sich mit den Textbausteinen. Diese werden pro Werbemittelcode, oder eben die Defaults, auf der Platte gespeichert.
Auch hier können wir diese nur aktualisieren, wenn wir den Reload forcen und den Cache leeren
Button nutzen.
Der Cache gilt natürlich nicht für die Textbausteine aus der src/Config/config.json
, diese werden immer "über" den Cache geschrieben.
Der Button Cache leeren
gilt immer für alle Sachen die auf dem Dateisystem gecacht werden, also die Aktualisierung des einen
oder anderen ist somit nicht möglich. Es wird dann immer alles aktualisiert. (Es sei denn man löscht manuell z.B. nur den jwt cache
aus dem Dateisystem).
Standardmäßig wird der Cache in /tmp/symfony-cache
geschrieben.
Fonts
Wenn wir Custom-Fonts brauchen, können wir diese ganz einfach einbinden. Zunächst brauchen wir die Fonts selber. Z.B.: ablegen unter src/Templates/fonts
.
Dann öffnen wir folgende Datei: src/Service/PdfService.php
. Hier müssen wir kleine Anpassungen an der verwendeteten mPDF
Instanz vornehmen:
private function _getInstance(): Mpdf
{
$defaultConfig = (new \Mpdf\Config\ConfigVariables())->getDefaults();
$fontDirs = $defaultConfig['fontDir'];
$defaultFontConfig = (new \Mpdf\Config\FontVariables())->getDefaults();
$fontData = $defaultFontConfig['fontdata'];
$mPdf = new Mpdf([
...
'fontDir' => array_merge($fontDirs, [
__DIR__ . '/../Templates/fonts', # auf Basis von src/Templates/fonts, kann aber natürlich irgendein Pfad sein
]),
'fontdata' => $fontData + [
'font-name' => [ # css: font-family: font-name;
'R' => 'Font-Name.ttf',
'B' => 'Font-Name-Bold.ttf',
'I' => 'Font-Name-Italic.ttf',
'BI' => 'Font-Name-BoldItalic.ttf',
],
],
]);
...
}
Für weiter Information über die Konfiguration von Fonts bei mPDF
, bitte hier klicken.