enhancement
major
minor
major
minor
major
#29543
TL-Ansichten: Bedingte Verzweigungen in einer Aktionskette mit generischen Befehlen
Problem
Ein <generic-command> (GenericViewCommand, com.top_logic.layout.view.command) ist eine Liste von ViewActions, die von `ViewActionChain.run` ausgeführt werden: Jede Aktion erhält das Ergebnis der vorherigen (ViewAction.execute(context, input) oder die asynchrone Form mit einer Continuation) und gibt ihr eigenes Ergebnis weiter. <execute-script>, <with-transaction>, <write-channel>, <open-dialog>, <close-dialog>, <navigate-pop> (#29530) und <show-object> (#29532) sind alle auf diese Weise aufgebaut.
Der einzige Kontrollfluss ist linear. Eine Kette kann vorzeitig enden – <confirm> bricht sie ab, wenn der Benutzer den Vorgang abbricht, <throw-error> lässt sie fehlschlagen –, aber sie kann nicht je nach dem von ihr übertragenen Wert zwischen zwei Möglichkeiten wählen. Beispiele aus dem auf der Ansichtsebene aufgebauten Issue-Tracker:
- Ein Suchfeld: Wenn ein Ticket mit dem eingegebenen Schlüssel existiert, wird es angezeigt; andernfalls wird die Ticketliste mit dem Begriff als Suchbegriff geöffnet.
- Ein Workflow-Befehl: Wenn das Ticket noch neu ist, annehmen und dem aktuellen Benutzer zuweisen; andernfalls nur zuweisen.
- Ein Handler zum Ablegen oder Erstellen: Wenn das Ziel das Objekt bereits enthält, nichts tun; andernfalls verschieben und auswählen.
Die Workarounds: zwei Befehle mit sich ergänzenden <visible-if> -Regeln (was nur funktioniert, wenn die Bedingung vom Eingabekanal abhängt, nicht von einem innerhalb der Kette berechneten Wert) oder ein einzelnes <execute-script>, das beide Alternativen selbst ausführt und nichts zurückgibt – wodurch die Kombination mit den deklarativen Aktionen aufgegeben wird, da ein Skript keinen Dialog öffnen, kein Objekt anzeigen und keinen Frame verlassen kann.
Lösung
Eine Verzweigungsaktion, deren Test eine TL-Script-Funktion über den Wert ist, den die Kette überträgt:
{{{#!xml <generic-command>
<execute-script function="key -> all(my.module:Ticket).filter(t -> $t.get(my.module:Ticket#name) == $key).firstElement()"/>
<if test="ticket -> $ticket != null">
<then>
<show-object/>
</then>
<else>
<write-channel name="searchTerm"/>
</else>
</if>
</generic-command> }}}
- <if test="…"> (IfAction) wertet die Funktion auf den aktuellen Kettenwert aus (mit optionalen Eingangskanälen als weitere Argumente, wie sie von <execute-script> und <confirm> verwendet werden; das Ergebnis ist eine Bedingung im „fuzzy“-Sinne von TL-Script) und führt die Aktionen von <then> oder <else> als verschachtelte Kette aus. Die verschachtelte Kette beginnt mit dem aktuellen Wert; ihr Ergebnis wird zum Wert der umschließenden Kette. Ein fehlender Zweig leitet den Wert unverändert weiter, sodass <if> mit nur <then> eine Schutzbedingung darstellt.
- <switch value="…"> (SwitchAction) für eine Mehrwegentscheidung. Die optionale Wertfunktion berechnet den Wert, über den die Fälle entscheiden; ohne sie ist der aktuelle Wert der Kette dieser Wert. Jedes <case> konfiguriert genau eine von zwei Bedingungen: match="…" ist ein TL-Script-Ausdruck ohne Parameter, dessen Ergebnis mit dem Switch-Wert unter Verwendung der Gleichheitsoperation von TL-Script (==) verglichen wird; ein Klassifikator wird also als ` `module:Enum#literal `, ein Text als `'text' und eine Zahl als die Zahl selbst geschrieben; test="…" ist ein Prädikat, das mit dem Switch-Wert aufgerufen wird, wobei dieser im „fuzzy“ Sinne von TL-Script interpretiert wird. Die Fälle werden der Reihe nach verglichen; der erste passende Fall wird ausgeführt, andernfalls der <default>.
{{{#!xml <switch value="t -> $t.get(demo.tickets:Ticket#status)">
<case match="demo.tickets:TicketStatus#closed">
<with-transaction>
<execute-script function="t -> $t.set(demo.tickets:Ticket#status, demo.tickets:TicketStatus#open)"/>
</with-transaction>
</case>
<case test="s -> $s == null">
<confirm expr="x -> #('Das Ticket hat keinen Status.'@en)"/>
</case>
<default>
<with-transaction>
<execute-script function="t -> $t.set(demo.tickets:Ticket#status, demo.tickets:TicketStatus#closed)"/>
</with-transaction>
</default>
</switch> }}}
- „Genau eines von match und test“ ist als Konfigurationsbeschränkung für die beiden Eigenschaften deklariert (@Constraint mit OnlySetIfUnset und dem neuen allgemeinen MandatoryIfUnset in com.top_logic.basic.config.constraint.impl), sodass der Konfigurationsformular-Editor einen Verstoß in diesem Feld meldet und ViewLoader.parseConfig den ConstraintChecker für jede geladene Ansicht ausführt, wodurch eine verletzte Einschränkung das Laden der Ansicht mit Angabe der Position des betreffenden Elements zum Scheitern bringt. ConstraintChecker protokolliert die übersetzte Fehlermeldung (mit Angabe der Eigenschaft und des Ortes) anstelle eines festen Textes.
- Verschachtelte Ketten werden über `ViewActionChain.nest` mit dem Continuation-Protokoll abgearbeitet, sodass asynchrone Aktionen – <confirm>, <open-dialog>, ein „Dirty-Form“-Veto bei <write-channel> – funktionieren innerhalb eines Zweigs genau wie auf der obersten Ebene; ein Abbruch innerhalb eines Zweigs bricht den gesamten Befehl ab, und innerhalb eines Zweigs registrierte Kompensationen behalten ihren Platz im Unwind des Befehls. ViewActionChain.run übergibt den Endwert der Kette an ihren Abschluss-Callback.
- „appliesFormState() “ einer verzweigten Aktion ist die Disjunktion über ihre Verzweigungen, sodass der Formularzustand vor der Kette angewendet wird, sobald eine Verzweigung ihn benötigt.
- ActionScript ist der einzige Ort, an dem alle skriptgesteuerten Aktionen (<execute-script>, <confirm>, <if>, <switch>) ihre Funktionen kompilieren und ihre Eingabekanäle auslesen; ViewActions instanziiert Aktionslisten und beantwortet deren appliesFormState.
Außerdem wurde dabei Folgendes behoben
Die „Save“- und „Cancel“-Kette eines <form> (FormElement) führte ihre Aktionen über eine selbst implementierte Schleife aus, die das synchrone `ViewAction.execute` aufrief, was bei jeder unterbrechbaren Aktion fehlschlug; nun läuft sie über `ViewActionChain`, sodass <confirm>, <if> und <switch> auch in den Aktionsketten eines Formulars funktionieren.
Tests, Dokumentation und Demo
TestBranchActions (tl-layout-view): synchrone und asynchrone Verzweigungen, Pass-Through, Abbruchweitergabe und Kompensationsreihenfolge, Fallabgleich mittels TL-Script-Gleichheit und Prädikat, Ablehnung einer Ansicht, deren Fall keine oder beide Bedingungen erfüllt, „appliesFormState“. TestConstraintChecker (tl-basic): „MandatoryIfUnset “ allein und in Kombination mit „OnlySetIfUnset“. docs/faq/react-view-layer.md dokumentiert die Verzweigungsaktionen neben der linearen Kette. com.top_logic.demo.react, Ansicht „Objektliste“: Ein Symbolleistenbefehl „Umschalten“ schaltet den Ticketstatus um und schließt ein offenes Ticket oder öffnet ein geschlossenes wieder.