major
#29530
URL-Routing in TL Views: Modellobjekte in Routenparametern, Drilldown-Pfad in der URL, Abfragebindungen
Problem
Die Ansichtsebene (com.top_logic.layout.view) spiegelt einen Teil ihres UI-Zustands in der Browser-URL wider: Der RouteManager setzt die Adresse aus den Segmenten der RoutingParticipants zusammen , die die Ansicht enthält, übermittelt Änderungen über SSE (`RouteChangeEvent`) an den Client und wandelt die Zurück-/Vorwärts-Funktionen des Browsers (Popstate) in einen „navigateToRoute“-Befehl um. Teilnehmer sind die Seitenleiste (ReactSidebarControl, ein Segment pro <nav-item>), die Registerkartenleiste (ReactTabBarControl) und die <param-bindings> auf Ansichtsebene (ParamBindingParticipant).
Was verhinderte, dass eine URL den Zustand beschrieb, den ein Benutzer tatsächlich sieht:
1. Routenparameter konnten keine Modellobjekte übertragen
„ParamBindingParticipant“ schreibt das URL-Segment in den gebundenen Kanal und den Kanalwert zurück in die URL, beides als Text. Ein Modellobjekt benötigte daher einen Text, der es identifiziert, und TL-Script bot keinen: Die registrierten Funktionen decken Modellteile (resolveModelPart), Enum-Literale (resolveEnum) und Aliase (resolveAlias) ab, aber keine liefert den Bezeichner eines Objekts oder findet ein Objekt anhand eines solchen wieder. Ein Objekt konnte nur über einen Geschäftsschlüssel in eine URL eingefügt werden, den ein Ausdruck nachschlagen konnte, z. B. `all(`demo.tickets:Ticket).filter(t -> $t.get(demo.tickets:Ticket#name) == $key).firstElement()“, allerdings auf Kosten der Eindeutigkeit und URL-Sicherheit, die ein solcher Schlüssel aufweisen muss.
Die klassische Benutzeroberfläche identifiziert Objekte in URLs über den BookmarkService und die Argumente #object=<id> seiner pluggbaren BookmarkHandler (aufgelöst durch den DefaultBookmarkHandler); nichts davon ist von der Ansichtsebene aus erreichbar.
2. Der Drilldown-Pfad des Kachelstapels ist nicht in der URL enthalten
<tile-stack> (com.top_logic.layout.view.tiles) speichert seinen Drilldown-Pfad als ` List<TileFrame> ` auf einem Kanal, und sowohl `<navigate-push>` als auch `<navigate-pop>` sind Schreibvorgänge auf diesen Kanal – dies ist beabsichtigt, damit „die URL-Persistenz zu einem normalen <param-bindings> -Anliegen außerhalb der Kachel-Infrastruktur wird“. Diese Anforderung ist jedoch nicht umgesetzt: Ein `TileFrame` besteht aus einer Ansichtsreferenz, einer Beschriftung sowie einem Snapshot der gebundenen Kanalwerte (typischerweise Modellobjekte), während ein Routenparameter lediglich einen einzelnen Text enthält. ReactTileStackControl ist ebenfalls kein RoutingParticipant. Der Drilldown-Zustand der Kachel-Demo (ein Konto auswählen, dessen Detailrahmen öffnen) bleibt daher weder nach einem Neuladen noch beim Klicken auf die Zurück-Schaltfläche erhalten.
Der Stack ist zudem nur über einen Java-ViewCommand erreichbar: <navigate-push>, <navigate-pop> und <navigate-pop-to> sind ViewCommands, die ihre eigene Beschriftung, ihr eigenes Bild, ihre eigene Platzierung und ihre eigene Ausführbarkeit mitbringen, sodass keiner von ihnen ein Glied in der Aktionskette eines `<generic-command>` sein kann, bei der das Ergebnis jeder ViewAction in die nächste einfließt (<execute-script>, <with-transaction>, <write-channel>, <open-dialog>). Eine Schaltfläche, die ein Objekt löscht und anschließend den Frame verlässt, in dem es angezeigt wurde, lässt sich daher nicht realisieren; aus diesem Grund befindet sich die Löschschaltfläche der Objektlisten-Demo in der Liste statt auf der Detailseite. Der Stack selbst benötigt keinen Namen – ein Frame erreicht ihn automatisch über den ` TileStackScope` in seinem `ViewContext` –, aber es gibt auch keinen deklarativen Zugriff auf den Pfad, sodass ein Befehl nicht von der Tiefe abhängen kann, in der er ausgeführt wird (beispielsweise eine Zurück-Schaltfläche, die sich im Start-Frame selbst deaktiviert).
3. Abfragebindungen existieren zur Laufzeit nicht
QueryBindingConfig und ViewElement.Config.getQueryBindings() sind zwar deklariert, aber die Eigenschaft wird nie gelesen: Es wird kein Teilnehmer erstellt, und es wird niemals eine Abfragezeichenfolge geschrieben oder geparst. Der Filterstatus (der dokumentierte Anwendungsfall: ?type=...&rooms=..., geschrieben mit `replaceState`, damit die Filtereingaben den Verlauf nicht überfluten) kann überhaupt nicht gebunden werden.
4. Die Funktion war undokumentiert und ungenutzt
<param-bindings> wurde von keiner Ansicht in der Engine oder in den Demo-Anwendungen verwendet, sodass der Codepfad außerhalb der Unit-Tests des RouteManagers nicht durchlaufen wurde. Weder die Routenbindung noch der Kachelstapel tauchten in docs/faq/react-view-layer.md auf; der Kachelstapel wurde lediglich in seiner „package-info“ und in einem Entwurfsplan beschrieben, weshalb er leicht übersehen werden kann, obwohl <tile-stack>, <tile-breadcrumb> und <navigate-push> @InApp sind und somit im Konfigurationseditor angeboten werden.
5. Fehler in der Routing-Laufzeitumgebung
Festgestellt bei der Objektlisten-Demo von com.top_logic.demo.react, die das ausgewählte Ticket an einen Routenparameter bindet:
- Segmente eines nicht angezeigten Teilbaums gelangten in die URL. Nachdem ein Deep-Link die Seitenleiste auf die Objektliste umgeschaltet hatte, lautete die Adresse „tickets/deeplink-demo/table“: „table“ ist das Tab-Segment der Attributansicht, also das zuvor aktive Element der Seitenleiste. Das Drücken der Zurück-Taste erzeugte daraufhin „table/tickets/deeplink-demo“ und „table/tickets“ – dasselbe Segment an unterschiedlicher Position. RouteManager.currentUrl() verkettete die Segmente in der Reihenfolge ihrer Registrierung, und Teilnehmer registrieren sich, wenn ihr Steuerelement angehängt wird, was bei einem Tab verzögert zum Zeitpunkt des Renderns geschieht (ReactTabBarControl.onBeforeWrite()). Die Reihenfolge der Registrierung folgte weder der Anzeigehierarchie noch wurde das verworfen, was die Anzeige verlassen hatte.
- Eine durch den Verlauf ausgelöste Routenänderung fügte einen Verlaufseintrag hinzu. Beim Zurückblättern wurde ein „RouteChangeEvent“ mit „replace = false“ ausgelöst, während der Browser bereits navigierte; dies fügt einen Eintrag an, anstatt einen zu verbrauchen, und führt dazu, dass wiederholtes Drücken der Zurück-Taste nicht monoton verläuft.
- Eine URL wurde nur von einer Anzeige übernommen, die noch nicht existierte. Eine ausstehende URL wird von Teilnehmern bei ihrer Registrierung verarbeitet – genau das geschieht, wenn eine Anzeige zum ersten Mal aufgebaut wird. Eine neu geladene Seite wird in den Steuerungsbaum gerendert, den das Fenster bereits enthält, dessen Teilnehmer registriert sind, bevor die zu übernehmende URL bekannt ist – daher ließ ein Deep Link in einen bestehenden Browser-Tab die Anzeige unverändert, und die Adressleiste behielt entweder eine URL bei, die nichts anzeigte, oder wurde mit dem Zustand überschrieben, den der Tab noch anzeigte. Ein Klick auf ein Element in der Seitenleiste fügte dessen Segment an einen solchen veralteten Pfad an, was zu /view/tickets/tickets führte.
- Eine ohne Route geladene Seite ließ die Adressleiste unvollständig. Die zusammengesetzte URL wurde zurückgehalten, da sich der Manager daran erinnerte, sie an den Client der vorherigen Seite gesendet zu haben, die die frisch geladene Seite jedoch noch nie gesehen hatte.
- Ein Routenparameter behielt ein Segment bei, das zu nichts führte. Der Teilnehmer meldete den konsumierten Text als sein Segment, selbst wenn die Bindung ihn zu keinem Objekt auflöste, sodass eine URL, die ein gelöschtes oder unbekanntes Objekt benannte, in der Adressleiste neben einer Ansicht verblieb, die kein solches Objekt anzeigte.
- Eine Navigation innerhalb der App erzeugte keinen Verlaufseintrag. Der Austausch der Anzeige ist die Art und Weise, wie eine Navigation durchgeführt wird, und die Teilnehmer, die auf dem Weg verschwanden und wieder auftauchten, meldeten ihre eigenen Korrekturen der Adressleiste. Eine solche Korrektur traf ein, bevor die Navigation sich selbst melden konnte, sodass die Adressleiste bereits das Ziel anzeigte – und der Nutzer keinen Eintrag hatte, zu dem er zurückkehren konnte. Das Umschalten des Seitenleistenelements in eine Ansicht mit Registerkarten zerstörte sogar den Eintrag der zurückgelassenen Ansicht.
- Eine verzögerte Auswahl erreichte die Hervorhebung, aber nicht die Anzeige. Die Auswahl eines Seitenleistenelements oder einer Registerkarte, bevor irgendetwas gerendert wurde, aktualisierte den Status, der die Auswahl benannte, ließ jedoch den Inhalt des vorherigen Elements an Ort und Stelle.
- Eine URL, zu der der Browser navigierte, wurde ohne Sitzungskontext übernommen. Der Befehl „navigateToRoute“ umging die Subsession- und Aktualisierungsphase, die jeder andere Befehl durchläuft, sodass ein an einen Routenparameter gebundener Kanal das durch die URL benannte Objekt nicht nachschlagen konnte: Durch Drücken der Zurück-Taste auf /view/tickets/<id> blieb die Liste ohne Auswahl, und die Adressleiste wurde auf den Zustand korrigiert, der noch angezeigt wurde.
- Eine URL, deren Bezeichnung weniger umfasste als die Anzeige, ließ die Anzeige unverändert. Eine URL, die in eine Sitzung übernommen wurde, die bereits einen Drilldown enthielt – die reine Ansichts-URL, die eingegeben wurde, während ein Frame geöffnet war, oder ein Deep-Link mit einer Kennung, die kein Objekt enthält –, behielt den Frame bei und schrieb die Adressleiste entsprechend um: Nichts wies den Teilnehmer darauf hin, dass die URL keine Route für ihn benannte. Eine durch ein „Dirty-Form“-Veto abgelehnte URL beendete ihre Übernahme ebenfalls nie, sodass die nächste Navigation des Benutzers als Ersatz statt als Verlaufseintrag gemeldet wurde.
- Ein Wert, der in einen Kanal geschrieben wurde, bevor dessen Tabelle angehängt wurde, wurde ignoriert. RowSourceObserver (hinter <table>, <object-list>, <calendar>) wertete die Zeilen einmalig bei der Erstellung aus und begann erst dann, seine Eingabekanäle abzuhören, wenn sein Steuerelement angehängt war, ohne erneut zu lesen. Ein Kanal, in den ein URL-Parameter beim Anfügen der Root schreibt – was dem Anfügen der darunterliegenden Tabelle vorausgeht –, erreichte daher den Filtereingang, aber nicht die Zeilen, bis der Benutzer den Filter bearbeitete. Dieselbe Lücke verschluckte jede Änderung, die vorgenommen wurde, während eine Anzeige abgetrennt war.
- Die beiden Stapel der Multi-Tab-Kachel-Demo teilten sich einen Pfad. Der Inhalt eines Tabs nutzt die Kanäle der umgebenden Ansicht, und die verschachtelten `<view>`-Elemente beider Tabs deklarierten `navPath`, sodass der zweite den Kanal des ersten übernahm: Ein Drilldown in einem Tab führte zu einem Drilldown in beiden.
Lösung
- `objectId ` und `objectResolve ` (ObjectFunctions, @ScriptPrefix("object")): die Kennung eines Objekts als Text für eine URL und das Objekt eines Typs mit einer bestimmten Kennung. Nichts für ein temporäres Objekt und nichts für eine Kennung, die kein Objekt des Typs trägt – ein gelöschtes Objekt, ein falsch eingegebener Link –, sodass ein unbrauchbarer Link kein Segment hinterlässt.
- Routenparameter, die ein Modellobjekt transportieren, über einen bidirektionalen abgeleiteten Kanal über diese beiden Funktionen.
- Eine URL, die aus dem Steuerbaum anstelle der Registrierungssequenz zusammengesetzt wird, ohne Beiträge von Teilnehmern, die die Anzeige verlassen haben.
- Ein Ersetzungsflag, das der Ursache einer Änderung folgt: Die Übernahme einer URL, die der Client bereits anzeigt, meldet keinen Verlaufseintrag, eine In-App-Navigation meldet genau einen, und eine Anzeigeänderung, die eine Navigation auslöst, wird als eine einzige Navigation und nicht als eine Reihe von Korrekturen behandelt. Eine Übernahme endet immer – mit `finishAdoption()`, wenn die URL übernommen wurde, oder mit `cancelAdoption()`, wenn sie durch ein Veto abgelehnt wurde – und nur ihr Ende wird in der Adressleiste gemeldet; daher melden Teilnehmer, die die Anzeige unterwegs verlassen und wieder betreten, nichts (ViewServlet, ReactServlet, AgentServlet).
- Eine vom Display übernommene URL, die bereits existiert – nicht nur eine, die gerade erstellt wird –, unterliegt demselben Kontext wie jeder andere Befehl. Ein Segment, das die Anzeige nicht reproduzieren kann, wird verworfen und in der Adressleiste korrigiert, und ein Teilnehmer, der eine Route anzeigt, in der die URL weder benannt noch eingebracht wurde, wird aufgefordert, resetRoute() auszuführen – auf diese Weise kehrt die reine URL einer Ansicht zu ihrem ursprünglichen Rahmen zurück.
- Eine URL, bei der ein Routenparameter nicht angegeben ist, behält den von der Ansicht festgelegten Wert bei – das Element, das eine Tabelle standardmäßig auswählt, oder die Auswahl, die die Sitzung enthält – und die Adressleiste wird damit vervollständigt.
- Routenparameterwerte sind prozentkodierte Pfadsegmente (RFC 3986, RouteEncoding, das von ` RoutePattern.produce ` angewendet und von ` RoutePattern.match` rückgängig gemacht wird), sodass ein Wert, der einen Schrägstrich, ein Leerzeichen oder ein Prozentzeichen enthält, das eine Segment bleibt, das er ausfüllt; die Server übernehmen eine URL in der Form, in der der Browser sie sendet (ViewServlet liest die Route aus der rohen Anfrage-URI). Ein kodierter Schrägstrich benötigt einen Container, der mehrdeutige Pfade akzeptiert: Das eingebettete Jetty von tl-ide-jetty erlaubt AMBIGUOUS_PATH_SEPARATOR und dekodiert mehrdeutige URIs; ein Produktionscontainer benötigt die entsprechende Einstellung (dokumentiert in docs/faq/react-view-layer.md; Objektbezeichner enthalten niemals einen Schrägstrich, daher betrifft dies nur Geschäftsschlüssel). Ein statisches Präfix in „ParamBindingConfig“ adressiert einen Parameter als „ticket/:ticket“ statt positionsabhängig.
- Der Drilldown-Pfad eines <tile-stack> in der URL: Der Stack deklariert seine Frames als <frame view="..." route="person/:person"> mit einer <param name expr reverse> -Konvertierung pro Parameter (Objekt zu Text, Text zu Objekt) und einem <label> -Provider, der den Frame benennt. Ein „TileFrameRouteParticipant“ pro eingebundenem Frame setzt die Routen jedes Frames auf dem Pfad zusammen und übernimmt die URL Frame für Frame (RoutingParticipant.acceptsRouteSequence), sodass ein Neuladen den Drilldown wiederherstellt und das Vor- und Zurücknavigieren ermöglicht. Ein Parameter, der zu nichts aufgelöst wird, beendet den Pfad, und ein Frame, der ohne Bezeichnung auf den Stack geschoben wird, übernimmt die Bezeichnung, die der Stack für seine Ansicht festlegt.
- <navigate-pop> und <navigate-pop-to> als ViewActions (`NavigatePopAction, NavigatePopToAction), einsetzbar in der Kette eines <generic-command> neben <execute-script>, <with-transaction> und <write-channel>, sodass ein Befehl seine Arbeit abschließen und anschließend den Frame verlassen kann, in dem er ausgeführt wurde. Die gleichnamigen Befehle delegieren an die Aktionen; ` TileStackScope.lookup ` ist die einzige Bereichsauflösung, die alle verwenden.
- „bind-path-to“ auf <tile-stack> benennt den Kanal, über den jeder Frame den Pfad sieht, sodass ein abgeleiteter Kanal die Tiefe angibt und eine <visible-if> -Regel eine Zurück-Schaltfläche im Start-Frame ausblendet.
- Eine Laufzeitumgebung für <query-bindings>: ein „QueryBindingParticipant“ pro Bindung, wobei die Abfragezeichenfolge aus einer übernommenen URL herausgelöst und jedem Teilnehmer angeboten wird (RoutingParticipant.activateQuery), und die Abfrageparameter aus den angezeigten Teilnehmern zusammengesetzt werden. Eine Änderung der Abfrage allein wird mit `replaceState` geschrieben, eine Änderung des Pfads mit `pushState`. `RowSourceObserver` liest seine Elemente neu ein, wenn er mit der Beobachtung beginnt, sodass ein Wert angezeigt wird, den eine URL vor dem Anhängen der Tabelle geschrieben hat.
- <text-input value="channel"> (TextInputElement): Ein Eingabefeld, das den Textwert eines Kanals in beide Richtungen schreibt und aus dem vorhandenen Text-Input-Steuerelement und dem Feldmodell zusammengesetzt ist – das Gegenstück zu einem <field> für einen Wert, der eher zur Ansicht als zu einem Modellobjekt gehört, wie beispielsweise ein Filterbegriff.
- Dokumentation zum URL-Routing und zum Drilldown im Kachelstapel in docs/faq/react-view-layer.md. Die Demos von com.top_logic.demo.react: Die Objektliste enthält das ausgewählte Ticket (/view/tickets/ticket/<id>) und den Filterbegriff (?q=) in der Adressleiste; die Kachel-Demo enthält ihren Drilldown (/view/tiles-demo/person/<id>) und zeigt einen tiefensicheren „Zurück“-Befehl an; die Multi-Tab-Kachel-Demo hält ihre beiden Stapel auf eigenen Kanälen.