major
#29532
Objektnavigation in TL Views: Anzeigeziele, ein „reveal“-Protokoll für Container und eine „show-object“-Aktion
Problem
In der klassischen Benutzeroberfläche wird ein Link zu einem Geschäftsobjekt auf dem Server aufgelöst: GotoHandler empfängt das Objekt, sucht nach der Komponente, die Objekte dieses Typs anzeigt (mit WithGotoConfiguration.getGotoTargets(), einer Zuordnung von TLType zu ComponentName mit einem globalen Standardwert), und „LayoutComponent.makeVisible()“ durchläuft den Komponentenbaum, sodass jeder übergeordnete Knoten – Registerkarte, Dialogfeld, Layout – das untergeordnete Element auf dem Weg zu dieser Komponente anzeigt. Objektverknüpfungen innerhalb von strukturiertem Text sind tlObject-Anker, die von TLObjectLinkUtil geschrieben werden; ein Klick führt den Steuerbefehl „OpenTLObjectLink“ aus, der das Objekt serverseitig auflöst und entweder dorthin navigiert oder es in einem Dialogfeld öffnet. Es ist nirgendwo eine clientseitige URL beteiligt.
Die Ansichtsebene (com.top_logic.layout.view) hat kein Gegenstück:
- Keine Anzeigeziele. Nichts legt fest, welche Ansicht ein Objekt eines bestimmten Typs anzeigt. Ein <form input="ticket">, ein <table selection="…"> oder ein <tile-stack> -Frame ist mit allen Anzeigeobjekten über „bind-input-to“ verknüpft, doch die Zuordnung „Objekte vom Typ T werden hier auf Kanal C angezeigt“ existiert nur implizit in TL-Script-Ausdrücken.
- Kein Reveal-Protokoll. Es gibt keine Operation, die ein bestimmtes Element sichtbar macht, indem sie jeden Container auf dem Weg von der Wurzel auffordert, das richtige untergeordnete Element anzuzeigen – das Äquivalent zu makeVisible(). Jeder Container verfügt über einen eigenen Statuskanal (das aktive Element der Seitenleiste, die aktive Registerkarte der Registerkartenleiste, der Pfad des Kachelstapels, der Dialogstapel), aber keiner von ihnen stellt „dieses untergeordnete Element anzeigen“ bereit.
- Keine Aktion zum Anzeigen von Objekten. Eine <generic-command> -Kette kann Kanäle beschreiben, Dialoge öffnen und Skripte ausführen, aber sie kann nicht anweisen: „Zeige dieses Objekt an, wo immer es angezeigt wird“. Die einzigen Navigationsaktionen sind <navigate-push>/`<navigate-pop>`, bei denen es sich um Befehle handelt (siehe #29530) und die voraussetzen, dass sich der Aufrufer bereits im richtigen Stapel befindet.
- Die clientseitigen Hooks hängen in der Luft. ReactResourceCellControl sendet einen goto-Befehl, wenn eine verlinkte Zelle angeklickt wird, und bietet setGotoListener(GotoListener) mit handleGoto(ReactContext, Object) an, aber nichts in der Engine ruft setGotoListener auf, und der einzige Ersteller (MetaResourceControlProvider) übergibt useLink = false. Strukturierter Text (I18NHtml) wird in der React-Benutzeroberfläche angezeigt, ohne dass tlObject -Anker verarbeitet werden.
Die Folge für eine Anwendung wie den auf der Ansichtsebene aufgebauten Issue-Tracker: Ein Ticket-Verweis in einer Beschreibung, eine Zuweisungszelle in einer Tabelle oder ein „Blockiert durch“-Eintrag in einem Formular können nicht verfolgt werden. Jeder solche Link müsste pro Website manuell eingerichtet werden, wobei man das konkrete Seitenleistenelement und den Stapel kennen müsste, was sich nicht verallgemeinern lässt – eine Anwendung muss ja gar keine Seitenleiste haben.
Eine weitere Anforderung: Die Anzeige eines Objekts kann mehrere aufeinanderfolgende Auswahlen erfordern. Ein Ticket eines Meilensteins eines Projekts, das in drei Ebenen tief angezeigt wird, ist nur durch die Auswahl des Projekts, dann des Meilensteins und schließlich des Tickets erreichbar – in einem Kachelstapel sogar über drei Frames mit separaten Kanal-Namensräumen hinweg. Eine einzelne Deklaration vom Typ „Typ T auf Kanal C“ kann dies nicht ausdrücken, und eine Tabelle, die ihr eigenes Modell austauscht, wenn sie nach einer Auswahl gefragt wird, die sie nicht enthält (der klassische Ansatz), führt zu instabilen Auswahl-/Modellschleifen.
Lösung
Drei generische Komponenten in com.top_logic.layout.view.navigation, von denen keine speziell Seitenleisten, Registerkartenleisten oder Kachelstapel kennt.
Anzeigeziele: der `DisplayTargetService`
Anzeigeziele werden global in der Konfiguration eines Dienstes deklariert und entsprechen den klassischen „goto“-Zielen. Die Anwendung entscheidet, an welcher der Stellen, an denen ein Typ angezeigt wird, ein Objekt dieses Typs dargestellt werden soll; eine Ansichtsdatei bleibt wiederverwendbar und weiß nicht, dass sie ein Navigationsziel ist; ein Bibliotheksmodul stellt in seinem Konfigurationsfragment Ziele für seine eigenen Typen bereit.
Ein Ziel benennt einen Typ und eine geordnete Liste der anzuzeigenden Ansichten, jeweils mit den festzusetzenden Kanalwerten (aus der React-Demo):
{{{#!xml <config service-class="com.top_logic.layout.view.navigation.DisplayTargetService">
<instance>
<targets>
<target type="tl.demo.projectManagement:Ticket">
<show view="projects/overview.view.xml">
<bind channel="project" expr="t -> $t.container()"/>
</show>
<show view="projects/milestones.view.xml"
label-expr="t -> $t.container().get(tl.demo.projectManagement:ProjectScope#name)">
<bind channel="project" expr="t -> $t.container()"/>
</show>
<show view="projects/tickets.view.xml"
label-expr="t -> $t.get(tl.demo.projectManagement:Ticket#milestone).get(tl.demo.projectManagement:Milestone#name)">
<bind channel="milestone" expr="t -> $t.get(tl.demo.projectManagement:Ticket#milestone)"/>
</show>
<show view="projects/ticket-detail.view.xml" label-expr="t -> $t.get(tl.demo.projectManagement:Ticket#title)">
<bind channel="ticket"/>
</show>
</target>
<target type="tl.demo.projectManagement:Mitwirkender">
<show view="projects/contributor-dialog.view.xml" dialog="true">
<bind channel="contributor"/>
</show>
</target>
</targets>
</instance>
</config> }}}
Ein <show> -Eintrag wird auf eine von drei Arten ausgeführt, je nachdem, wie die Ansicht aufgerufen wird:
- Die Ansicht wird an einer beliebigen Stelle in der Anwendung eingebunden (ein Seitenleistenelement, eine Registerkarte, ein <view-ref>, ein <adaptive-detail> -Fenster, die Startansicht eines <tile-stack>): Die Einbindung wird offengelegt (siehe unten) und die Bindungen werden in der deklarierten Reihenfolge in die Kanäle der Ansicht geschrieben.
- Die Ansicht wird nicht eingebunden: Sie wird als Frame auf den Kachelstapel geschoben, der die zuvor angezeigte Ansicht enthält, wobei die Bindungen als gebundene Werte des Frames und label/`label-expr` als Breadcrumb-Bezeichnung dienen. Eine Kette solcher Einträge bildet einen Drilldown-Pfad nach; Frames, die sich bereits auf dem Stapel befinden und dieselbe Ansicht, dieselben Werte und dieselbe Bezeichnung aufweisen, werden beibehalten (Pop bis zum längsten übereinstimmenden Präfix, Push für den Rest), sodass ein Ziel, das einen Frame erreicht, in den der Benutzer manuell eingedrillt ist, diesen wiederverwendet.
- dialog="true": Die Ansicht wird als Dialogfeld geöffnet, wobei die Bindungen als anfängliche Kanalwerte dienen (genau wie bei <open-dialog> ); dies muss der letzte Eintrag sein.
Ein <bind> -Ausdruck ist eine TL-Script-Funktion des angezeigten Objekts; standardmäßig ist dies das Objekt selbst. Der spezifischste Typ hat Vorrang (eine exakte Klasse hat Vorrang vor einer Verallgemeinerung); bei mehreren Zielen für einen Typ wird dasjenige bevorzugt, dessen erste Ansicht am nächsten an der Ansicht liegt, die die Navigation ausgelöst hat, dann dasjenige mit der Kennzeichnung default="true" und schließlich das zuerst deklarierte. hasTarget(type) gibt an, ob Objekte eines Typs überhaupt angezeigt werden können – dies entscheidet darüber, ob ein Wert als Link dargestellt wird. Beim Start überprüft der Dienst jeden <bind channel> anhand der Kanäle, die seine Ansicht deklariert, und protokolliert bei einer Nichtübereinstimmung einen Konfigurationsfehler.
Wo eine Ansicht eingebunden wird, wird durch einen statischen Scan der Ansichtskonfiguration bestimmt, die von der Stammansicht der Anwendung aus erreichbar ist: UIElement.getChildGroups() meldet den Inhalt eines Elements ohne Sitzung – indiziert nach Inhalt, den ein Container über einen Schlüssel adressiert (Sidebar-Element-ID, Registerkarten-ID, adaptives Detailfenster, Startansicht des Kachelstapels), andernfalls unindiziert und als eingebettete Ansicht für ein <view-ref> – und ViewMounts leitet daraus die Einbindepfade jeder Ansichtsdatei ab, die zusammen mit den Ansichtsdateien zwischengespeichert und ungültig gemacht werden. Seitenleistenelemente und Registerkarten erzeugen ihren Inhalt verzögert, weshalb diese Informationen nicht aus dem Steuerbaum stammen können.
Ein Reveal-Protokoll für Container
Jedes Steuerelement, das eines von mehreren untergeordneten Elementen anzeigt, implementiert ` ChildRevealer.revealChild(key)`: Die Seitenleiste aktiviert das Element, die Registerkartenleiste wählt die Registerkarte aus, <adaptive-detail> wechselt zu seinem Bereich, der Kachelstapel springt in den Rahmen, ein Dialog schließt die darüber liegenden Dialoge; <switch> benötigt nichts (es folgt seiner Eingabe). Container speichern ihre Position, wenn sie die Kontexte ihrer untergeordneten Elemente erstellen (ein „RevealPath“- Gültigkeitsbereich im „ViewContext“, analog zum Slot-Pfad), und ein „RevealRegistry“ pro Browserfenster ordnet eingebundene Ansichten und Container ihren Laufzeitinstanzen zu. Das Einblenden einer eingebundenen Ansicht durchläuft ihren Einbindungspfad von der Wurzel aus und fordert jeden Container auf dem Weg auf, das nächste untergeordnete Element einzublenden – wodurch Inhalt erstellt wird, der verzögert generiert wird – und schreibt dann die Bindungen in die am Ende gefundene Ansichtsinstanz. Dies entspricht makeVisible() für Ansichtselemente. Ungespeicherte Änderungen verhindern das Anzeigen genau so, wie sie das Schreiben in einen Kanal verhindern (Bestätigungsdialog, dann erneuter Versuch; ein Abbruch beendet die Befehlskette). Die Routing-Teilnehmer von #29530 sind dieselben Container, sodass die Adressleiste den angezeigten Zustand ohne zusätzlichen Aufwand widerspiegelt.
Eine `show-object`-Aktion und automatische Links
<show-object/> ist eine ViewAction, die in einer <generic-command> -Kette neben <execute-script>, <with-transaction> und <open-dialog> verwendet werden kann: Sie zeigt das von der Kette übergebene Objekt an und leitet es weiter; <generic-command input="selection"><show-object/></generic-command> ist die vollständige Konfiguration einer „Gehe zu“-Schaltfläche. Der Java-Code ruft `ObjectNavigation.show` auf. Steuerelemente von com.top_logic.layout.react erreichen denselben Vorgang über ReactContext.getObjectNavigator() (canShow, show), worauf die Ansichtsebene reagiert, sodass als schreibgeschützt angezeigte Objektwerte automatisch zu Links werden, sofern für ihren Typ ein Anzeigeziel vorhanden ist:
- ReactResourceCellControl – Baumknoten (über MetaResourceControlProvider) und jede mit useLink erstellte Zelle; ein GotoListener hat, sofern gesetzt, weiterhin Vorrang.
- Die schreibgeschützten Werte von „ReactDropdownSelectControl“, mit dem Referenzattribute in <table> -Zellen und in Feldern im Ansichtsmodus <form> angezeigt werden – so kann man einem Zuweisungsempfänger in einer Tabelle oder einem „Blockiert durch“-Eintrag in einem Formular folgen.
- tlObject -Anker in strukturiertem Text, der vom React-WYSIWYG-Steuerelement schreibgeschützt angezeigt wird: Ein Klick wird an den Server gesendet (showObjectLink), das Objekt wird mit TLObjectLinkUtil wie beim klassischen OpenTLObjectLink aufgelöst und angezeigt; ein Link zu einem gelöschten Objekt oder zu einem Typ ohne Ziel wird dem Benutzer gemeldet.
Die TL-Script-Funktionen htmlObjectLink(object, label), htmlSource(content) und htmlText(source) (HtmlFunctions, com.top_logic.layout.wysiwyg) schreiben einen solchen Anker und lesen bzw. schreiben den HTML-Quelltext eines Strukturtext-Attributs, sodass ein Befehl eine Objektreferenz an einen Kommentar anhängen kann.
Befehle in der Symbolleiste des WYSIWYG-Editors und das Steuerelement, mit dem ein Feld bearbeitet wird
Zwei allgemeine Ergänzungen ermöglichen es einem Editor, eine Schaltfläche „Auf ein Objekt verweisen“ anzubieten, so wie es das klassische Editor-Plugin „CreateTLObjectLink“ tut, ohne dass der Editor etwas über Objekte wissen muss:
- Ein Feld wählt sein Eingabesteuerelement in der Ansicht aus. <field attribute="content"><input-control class="…Provider" …/></field> (FieldElement.Config) benennt den ReactFieldControlProvider, der dieses Feld an der Stelle bearbeitet, an der es angezeigt wird, und überschreibt dabei die <input-control> -Annotation des Modells, die Auswahlregel und die Typzuordnung (FieldControlService.createFieldControl mit einem expliziten Provider). Ein Steuerelement, das zu einer bestimmten Stelle in der Benutzeroberfläche gehört – ein Editor, dessen Symbolleiste einen Dialog genau dieser Ansicht öffnet –, wird in der Ansicht konfiguriert, sodass das Modell weiterhin festlegt, was das Attribut ist, und die Ansicht, wie es dargestellt wird.
- Die Symbolleiste des WYSIWYG-Editors enthält konfigurierte Ansichtsbefehle. WysiwygControlProvider akzeptiert <commands> – gewöhnliche ViewCommands mit Label, Icon, Ausführbarkeit, `input=, <open-dialog>, <execute-script> und so weiter – sowie ein optionales insert-channel="<name>". Die Befehle werden in einem untergeordneten `ViewContext` des Ansichtskontexts des Feldes ausgeführt: Sie erkennen die Kanäle der umgebenden Ansicht (das ausgewählte Ticket, das Projekt) und leiten diese an die von ihnen geöffneten Dialoge weiter. Wird ein Einfügekanal deklariert, existiert dieser in diesem Kontext neben den Kanälen der Ansicht, und ein darin geschriebener String wird an der Cursorposition eingefügt: Das Steuerelement sendet eine einmalige Einfügeanforderung {seq, html}, der Client fügt diese einmal pro seq an der aktuellen Auswahl ein und meldet den resultierenden Text zurück, wodurch die Anforderung zurückgenommen wird (ein neu eingebundener Client wiederholt dies niemals). Die Befehle werden von ToolbarBuilder in ein ReactToolbarControl eingebunden (standardmäßig nur mit Symbolen, wie die Formatierungsschaltflächen), das als untergeordnetes Steuerelement der Symbolleiste bereitgestellt und vom Client neben seinen eigenen Schaltflächen gerendert wird. ViewCommands enthält den Code für den Modellaufbau und den Lebenszyklus, der mit den Elementen geteilt wird, die <commands> deklarieren.
Der Kommentar-Editor der React-Demo konfiguriert dies in tickets/comment-composer.view.xml:
{{{#!xml <field attribute="content" label-position="hide-label">
<input-control class="com.top_logic.layout.react.wysiwyg.WysiwygControlProvider" insert-channel="insert">
<commands>
<generic-command image="css:ri-links-line" input="ticket">
<label><en>Ticket referenzieren...</en><de>Ticket referenzieren...</de></label>
<executability><null-input-disabled/></executability>
<open-dialog dialog-view="tickets/reference-ticket.view.xml">
<bind channel="context" to="ticket"/>
<bind channel="result" to="insert"/>
</open-dialog>
</generic-command>
</commands>
</input-control>
</field> }}}
Der Dialog erhält das Ticket, zu dem der Kommentar gehört, als Kontext, und seine Einfügeaktion lautet <execute-script function="t -> htmlObjectLink($t)"/><write-channel name="result"/><close-dialog/> – der gesamte Vertrag zwischen einem Selektor und dem Editor. Der frühere Befehl „Ticket referenzieren“ des Composers fügte den Link am Ende des Textes ein, indem er den Entwurf umschrieb, und war deaktiviert, solange das Pflichtfeld einen Fehler anzeigte, da seine Aktion „store-form-state“ die Regel „FormValid“ darauf anwendete. Der eingefügte Link enthält die Attribute „target“ und „rel“, die die TipTap-Link-Erweiterung jedem Anker hinzufügt; sie haben keinen Einfluss auf das Folgen des Links.
Ebenfalls nebenbei behoben
- Ein <table> zeigte keine Auswahl an, deren Kanal bereits bei der Erstellung der Tabelle benannt war (ein Drilldown-Frame erhält seine Auswahl als Parameter): Die Zeile blieb unmarkiert. Nun wird die ursprüngliche Auswahl übernommen.
- TLObjectLinkUtil.getLink/`getLinkDestination` akzeptieren jedes TLObject, nicht nur einen Wrapper.
- OpenDialogAction.openDialog gibt das DialogHandle des geöffneten Dialogs zurück; DialogManager kann die Dialoge oberhalb eines bestimmten Dialogs schließen.
Dokumentation und Demo
docs/faq/react-view-layer.md beschreibt Anzeigeziele, den Mount-Scan, das Reveal-Protokoll, die Einstiegspunkte, die Auswahlsteuerung auf Feldebene und die Befehlsleiste des Editors. com.top_logic.demo.react enthält einen „Projects“-Drilldown (Projekt, Meilenstein, Ticket, Detail), deren Typen Anzeigeziele haben, ein Mitwirkenden-Dialogziel, tl.accounts:Person, das in der Kachel-Demo gezeigt wird (dessen Anfangsansicht dreimal gemountet wird, wodurch die „Nearest-Mount“-Regel angewendet wird), und der Kommentar-Editor der Objektliste verweist über einen Befehl in der Befehlsleiste des Editors auf ein Projekt-Ticket; der gerenderte Kommentar, die Zuteilungszelle, das Meilenstein-Feld und die Konto-Werte sind navigierbar.