enhancement
major
minor
major
minor
minor
#29611
TL-Ansichten: Die Aktion `<notify>` zeigt einen übersetzten Hinweis in einer generischen Befehlskette an (Snackbar oder OK-Dialog, wobei die Kette optional unterbrochen wird); `<throw-error>` wurde entfernt
Problem
Eine <generic-command> -Kette, die eine Eingabe ablehnt, verfügt über keine Aktion, die dem Benutzer lediglich den Grund dafür mitteilt. Zwei Fälle aus dem Issue-Tracker tl-dev:
- Die Ticket-Suche in der App-Leiste (#29542 <value-input> mit <on-submit>): Ein Suchbegriff, der kein Ticket benennt. Der <else> -Zweig des <if> (#29543) sollte „Kein Ticket TL-999999.“ anzeigen und die Kette beenden.
- Das Ablegen mehrerer Tickets auf der „Done“-Spur (#29545), deren „Resolve“-Dialog pro Ticket erfolgt: Die Kette lehnt mit der Meldung „Legen Sie jeweils nur ein Ticket ab, um es zu schließen.“ ab.
Was bereits vorhanden ist: <throw-error message="…"> akzeptiert eine feste Zeichenfolge – kein ResKey, kein i18n-Literal, kein Argument aus dem Kettenwert – und wird in der JavaDoc als Testhilfe bezeichnet; <confirm expr="…"> akzeptiert eine i18n-Funktion des Kettenwerts, rendert jedoch immer einen Ja/Nein-Dialog (ConfirmDialogControl erstellt beide Schaltflächen), der eine Frage stellt, die der Benutzer nicht beantworten kann. Die Apps missbrauchen daher entweder <confirm> als Hinweis oder rufen das TL-Skript throw(#('…'@en, '…'@de).fill($term)) auf, das einen ScriptAbort auslöst und zufällig als Snackbar des Fensters mit einer INFO-Zeile im Protokoll erscheint.
Lösung
Eine Aktion, <notify> (NotifyAction), teilt dem Benutzer innerhalb einer Befehlskette etwas mit:
<if test="ticket -> $ticket != null">
<then>…</then>
<else>
<notify kind="warning" stop="true" expr="term -> #('No ticket {0}.'@en, 'Kein Ticket {0}.'@de).fill($term)"/>
</else>
</if>
- expr (mit <inputs>, ausgewertet wie <confirm>: zuerst die Werte der Eingabekanäle, zuletzt der Wert der Kette) berechnet die Meldung – ein i18n-Literal, einen Ressourcenschlüssel oder einen Text. null oder ein leerer Text bedeuten, dass nichts zu sagen ist: Die Kette wird unverändert fortgesetzt.
- kind="info|warning|error" (Standard: info) gibt den Schweregrad an: die Snackbar-Variante oder den Titel des Dialogfelds.
- display="snackbar|dialog" (Standard: snackbar). Die Snackbar-Meldung wird flüchtig angezeigt und ist synchron (innerhalb von <with-transaction> verwendbar). Der Dialog zeigt die Meldung mit einer einzigen OK-Schaltfläche an und unterbricht die Kette, bis er geschlossen wird (OK, Escape, X oder Hintergrund), wie es auch bei <confirm> der Fall ist; ein Kontext ohne Dialogmanager greift auf die Snackbar zurück.
- stop="true" (Standard: false) beendet die Kette nach der Meldung: Es werden keine weiteren Aktionen ausgeführt, die Kompensationen der ausgeführten Aktionen werden durchgeführt, und es wird nichts protokolliert oder als Fehler gemeldet – eine abgelehnte Eingabe bedeutet, dass der Befehl wie beabsichtigt funktioniert. Ohne „stop“ wird der Wert unverändert weitergeleitet, sodass eine Benachrichtigung eine Kette auch beenden („Gespeichert.“) oder in deren Mitte stehen kann.
- title (Ressourcenschlüssel) benennt den Dialog; standardmäßig folgt der Titel der Art.
Der Dialog wird durch ein wiederverwendbares `MessageDialogControl ` in der React-Steuerungsschicht neben `ConfirmDialogControl` erstellt.
<throw-error> wurde entfernt: Eine Meldung mit stop="true" deckt dessen einzige Verwendung ab, und ein echter Fehler wird durch die TL-Script-Funktion throw(#('…'@en).fill(…)) innerhalb von <execute-script> ausgelöst, die eine i18n-Meldung enthält und wie jeder andere Fehler über CommandErrors gemeldet wird. Die Demo zur Fehlerbehandlung von tl-demo-react nutzt dies stattdessen und zeigt die verschiedenen Hinweisvarianten an.
Dokumentation in docs/faq/react-view-layer.md neben <confirm>.
Migration
<throw-error message="…"/> in einer .view.xml-Datei wird durch <notify kind="error" stop="true" expr="x -> #('…'@en)"/> ersetzt, wenn die Kette lediglich mit der Meldung enden soll, oder durch <execute-script function="x -> throw(#('…'@en))"/>, wenn der Befehl fehlschlagen soll.