enhancement
major
minor
major
minor
major
#29542
TL Views: Kanalgebundene Werteingaben für jeden Primitiv- und Referenztyp mit einem „Submit“-Hook
Problem
Jede Eingabe in der Ansichtsebene (com.top_logic.layout.view) ist ein <field attribute="…"/> innerhalb eines <form input="…">: Es bearbeitet ein Attribut eines Modellobjekts, und `FieldControlService.createFieldControl(context, part, fieldModel) ` wählt das Steuerelement anhand des ` TLStructuredTypePart ` des Attributs aus (die Provider und Werttyp-Provider von `FieldControlService.Config` sowie die `<input-control>` -Annotation des Attributs).
Die einzige Ausnahme bildete <text-input value="channel"> (TextInputElement, #29530): ein Eingabefeld, dessen Wert zur Ansicht gehört, nicht zu einem Modellobjekt, und das direkt an einen Kanal gebunden ist. Es wurde manuell aus einem `AbstractFieldModel` und einem `ReactTextInputControl` erstellt und existierte ausschließlich für Text.
Ein Wert, der der Ansicht gehört, ist nicht immer Text: die Grenze eines Datumsbereichs, eine Zählung, ein Umschalter, ein Enum-Literal, ein Verweis auf ein Projekt oder eine Person, die aus Optionen ausgewählt wurde. Ein solcher Wert konnte nur eingegeben werden, indem man ihn in ein Modellobjekt einbettete: einen transienten Typ mit einem Attribut, ein <form> über einer transienten Instanz davon und einen Kanal, der aus diesem Objekt geschrieben wurde. Der auf der Ansichtsebene aufgebaute Issue-Tracker wählt das Projekt eines neuen Tickets genau auf diese Weise aus (TicketTarget, ein transienter Typ mit einer einzigen Projektreferenz, der in einem Dialogformular bearbeitet wird), und jeder Filter, der kein Textbegriff ist, müsste dasselbe tun.
Die zweite Lücke: Eine Eingabe konnte keinen Befehl auslösen. Die Eingabe von „Enter“ in ein Textfeld hatte keine Wirkung; die einzige Möglichkeit, auf den Wert einzuwirken, war ein separates <button>, dessen Befehl den Kanal ausliest. Ein Eingabefeld „Ticket mit diesem Schlüssel öffnen“ in der App-Leiste, ein Filterbegriff, der bei „Enter“ angewendet wird, ein Schnellhinzufügungsfeld – alle benötigen die Tastatur zum Absenden.
Die dritte Lücke: Ein Eingabefeld außerhalb eines <form> hatte kein Layout. Ein <field> wird niemals allein gerendert – sein <form> rendert das responsive Raster um seine Felder herum, das diese vom Containerrand versetzt, sie auf Spalten verteilt und jede Beschriftung je nach Spaltenbreite neben oder über dem entsprechenden Eingabefeld platziert. Ein an einen Kanal gebundenes Eingabefeld rendert das gleiche Feld-Chrome direkt in einen bündigen Container, sodass es unabhängig von der Breite ohne Abstand und mit einer feststehenden seitlichen Beschriftung angezeigt wird.
Lösung
Ein `<value-input>`-Element für jeden Werttyp
<value-input value="channel" type="…"> (ValueInputElement) ersetzt <text-input>: ein Eingabefeld, das in zweierlei Weise an einen Kanal gebunden ist, dessen Steuerelement durch den deklarierten Typ bestimmt wird:
{{{#!xml <value-input value="term" type="tl.core:String" label="…"/> <value-input value="due" type="tl.core:Date"/> <value-input value="onlyOpen" type="tl.core:Boolean"/> <value-input value="status" type="demo.tickets:TicketStatus"/> <value-input value="project" type="my.module:Project" options="all(my.module:Project).filter(p -> $p.get(my.module:Project#active))"/> <value-input value="assignees" type="tl.accounts:Person" multiple="true"/> }}}
- „type“ ist ein Primitivtyp (Standard: tl.core:String), eine Aufzählung oder eine Klasse; options (ein TL-Script-Ausdruck, optional über <inputs> -Kanäle, deren Werte seine Argumente sind, der neu ausgewertet wird, wenn sich eines davon ändert) liefert die Auswahlmöglichkeiten einer Aufzählung oder eines Referenzeingangs, wobei standardmäßig die Literale der Aufzählung und alle Instanzen einer Klasse verwendet werden; multiple macht den Wert zu einer Sammlung; label, readonly und label-position wie bei <field>.
- Der Kanal wird geschrieben, wenn der Wert bestätigt wird (bei „change“ für „select“, „date“ oder „checkbox“, bei „blur“ oder „Enter“ für „text“), und ein von anderswo geschriebener Kanalwert – ein URL-Parameter, ein <write-channel> – wird vom Eingabefeld angezeigt (ChannelFieldBinding, die wiederverwendbare bidirektionale Bindung zwischen einem Kanal und einem FieldModel).
- Die Auswahl des Steuerelements erfolgt über denselben „FieldControlService“: Seine typbasierte Weiterleitung ist der grundlegende Einstiegspunkt, „createFieldControl(context, TLType, FieldSpec, FieldModel)“ mit „fieldSpec(type, annotations, label, multiple, model)“; der attributbasierte Pfad baut darauf auf und fügt lediglich die Suche nach der <input-control> -Annotation hinzu. Die vorhandenen Provider bedienen beide Pfade unverändert.
- Das Tag ist „value-input“, nicht „input“: 21 Elementkonfigurationen deklarieren eine „input “-Kanal-Eigenschaft, und ein „content“-Tag „input“ innerhalb eines Containers mit untergeordneten Elementen ist für den Konfigurationsleser mehrdeutig in Bezug auf diese Eigenschaft.
- <text-input> wurde entfernt; seine Verwendungen (die Objektlisten-Demo, die Dokumentation) lauten nun <value-input type="tl.core:String">.
Ein Submit-Hook
Ein Eingabefeld kann einen Befehl benennen, der mit seinem bestätigten Wert ausgeführt werden soll:
{{{#!xml <value-input value="key" type="tl.core:String">
<on-submit>
<execute-script function="key -> all(demo.tickets:Ticket).filter(t -> $t.get(demo.tickets:Ticket#name) == $key).firstElement()"/>
<write-channel name="ticket"/>
</on-submit>
</value-input> }}}
- <on-submit> enthält eine gewöhnliche ViewCommand-Konfiguration, deren Standardwert <generic-command> ist, sodass die Aktionen direkt darin stehen; der Befehl wird einmalig mit dem Element instanziiert und verfügt über eigene Ausführungsregeln, die anhand des übermittelten Werts ausgewertet werden.
- Bei der Eingabe in ein einzeiliges Text- oder Zahlenfeld (ReactFormFieldControl.hasSubmitGesture(), der Submit-Befehl des Clients, setSubmitListener) wird zunächst der Kanal beschrieben und anschließend der Befehl mit dem übermittelten Wert ausgeführt; ein Select-Element, ein Datumsfeld oder ein Kontrollkästchen wird beim Commit eines ausgewählten Werts über den Commit-Listener der Bindung übermittelt. Ein mehrzeiliges Textfeld verfügt über keine Übermittlungsgeste.
- ViewCommandModel.forCommand(ViewContext, ViewCommand, ViewCommand.Config) und ViewCommandModel.execute(ReactContext, Object input) führen einen konfigurierten Befehl mit einer vom Aufrufer bereitgestellten Eingabe aus; der Klick auf eine Schaltfläche ist derselbe Aufruf mit dem Wert des Kanals.
Das Feldraster für sich allein: `<fields>`
<fields> (FieldsElement) ordnet seinen Inhalt als Felder eines Formulars an, und zwar für Eingaben, die zur Ansicht gehören und daher außerhalb eines <form> stehen:
{{{#!xml <fields>
<value-input value="term" type="tl.core:String" label="…"/>
<value-input value="status" type="demo.tickets:TicketStatus" label="…"/>
</fields> }}}
- Es rendert dasselbe responsive Raster, das ein <form> um seine Felder herum rendert (ReactFormLayoutControl, React-Komponente TLFormLayout): den Seitenversatz, den dieser Inhalt im Abstandsmodell besitzt, die automatische Anpassung der Spalten an die maximale Spaltenanzahl (standardmäßig 3) sowie den Layout-Kontext, der eine Beschriftung von der Seite des Eingabefelds nach oben verschiebt, wenn die Spalte schmaler wird.
- „label-position“ kann „auto“ (responsiv, Standard), „side“ oder „top“ sein; Positionen auf Feldebene werden als Konfigurationsfehler abgelehnt. com.top_logic.layout.react.control.layout.„LabelPosition“ ist hierfür auf „ExternallyNamed“ gesetzt; ihr externer Name ist sowohl der in der Konfiguration angegebene Wert als auch der an den Client gesendete Wert.
- Ein <form> benötigt keine <fields>, da es bereits ein solches Raster ist; ein <field> benötigt weiterhin ein <form>, da <fields> kein Objekt enthält.
Dokumentation und Demo
docs/faq/react-view-layer.md beschreibt ansichtsbezogene Werte, das <value-input> -Element, den „submit“-Hook und das <fields> -Raster. com.top_logic.demo.React, Ansicht „Objektliste“: Der Filterbegriff ist ein <value-input>, ein Status- <value-input> über die TicketStatus- Enumeration schränkt beide Ticketlisten ein, und ein Eingabefeld „Zum Ticket springen“ wählt das Ticket aus, dessen Name bei Drücken der Eingabetaste eingegeben wird; alle drei befinden sich in einem <fields>. Tests: TestValueInputElement, TestFieldsElement (tl-layout-view).
Migration
<text-input value="…"/> existiert nicht mehr; schreibe <value-input value="…" type="tl.core:String"/> (der Typ kann weggelassen werden, tl.core:String ist der Standard). Die Attribute „value“ und „label“ bleiben unverändert. Ein <value-input>, das außerhalb eines <form> steht, wird in ein <fields> -Element eingefügt, um die Abstände, Spalten und responsiven Beschriftungen eines Formulars zu übernehmen.
Betroffen sind nur Projekte, die einen Snapshot nach 8.0.0-alpha8 verwendet haben; <text-input> war in keiner Version enthalten.