enhancement
major
minor
major
minor
minor
#29606
TL Views: Ein `<color token>`, das ein Token benennt, das das React-Theme nicht ausgibt, führt dazu, dass die Pill ohne Farbgebung und ohne Fehlermeldung gerendert wird.
Problem
<color token="…"/> (TLColor, #29546) bezeichnet ein Design-Token des UI-Themes; die Pille wird mit var(--<token>) als Farbe gerendert. Die React-Benutzeroberfläche gibt die Token aus der Datei „tl-react-theme.config.xml“ (UIThemeService) als benutzerdefinierte CSS-Eigenschaften aus: support-error, support-success, support-warning, interactive, text-secondary, … Die klassischen Design-Einstellungen (com.top_logic.themes.core, theme-settings.xml) definieren weitere Namen wie support-info und support-danger, die das React-Design jedoch nicht ausgibt.
Eine Anmerkung, die einen der letztgenannten Namen trägt (gefunden beim Einfärben der Prioritätsliterale des Issue-Trackers „tl-dev“ mit „support-info“ und „support-danger“), wird ohne jegliche Meldung akzeptiert: Das Modell wird geladen, das Doclet und der Konfigurationsprüfer geben keine Rückmeldung, die Pill wird mit „background: var(--support-info) gerend ert, was zu nichts aufgelöst wird, sodass der Wert als reiner Text angezeigt wird. Nichts im Protokoll weist auf die Ursache hin; sie wurde durch „getComputedStyle“ im Browser entdeckt.
Lösung
Der Token-Name wird anhand der Design-Tokens validiert, die die Anwendung tatsächlich ausgibt, und diese Tokens werden zur Auswahl angeboten.
Zwei Register derselben Art
Eine Anwendung verfügt über zwei Register für benutzerdefinierte CSS-Eigenschaften, wobei es sich um denselben Mechanismus handelt, der zweimal implementiert wurde:
- die klassischen Theme-Einstellungen – ThemeSetting / ThemeSettings, die aus der Datei „WEB-INF/themes/<id>/theme-settings.xml“ gelesen, entlang der Theme-Kette zusammengeführt und von CSSBuffer als :root { --<name>: <value>; } -Block am Ende des generierten Theme-Stylesheets ausgegeben, wobei pro Tag eine Einstellungsart (<color>, <dim>, <int>, <size>, <string>, … sowie die servereigenen Arten, die keine CSS-Variablen sind);
- die UI-Theme-Token – ThemeToken / UITheme / UIThemeService in com.top_logic.layout.react, ausgegeben als Inline-Element <style> mit dem Scope „data-theme“.
61 Namen kommen in beiden vor, wobei 57 davon denselben Wert haben – der Token-Satz der React-Benutzeroberfläche ist eine Teilmenge des klassischen Satzes. Die beiden sind dennoch zur Laufzeit disjunkt: Eine Seite der React-Benutzeroberfläche erhält nur die Token von UIThemeService (ViewServlet greift niemals auf Theme zu), eine klassische Seite nur den Block ihres Themes. Ein Name wird daher in der einen Benutzeroberfläche aufgelöst, in der anderen jedoch nicht, was den Fehler erst möglich macht.
Die Nahtstelle
ColorSpec befindet sich im Kernmodul com.top_logic, sodass es die klassischen Einstellungen lesen kann, nicht jedoch die Token des darüberliegenden React-Moduls. Das Kernmodul deklariert daher DesignTokenService, die Schnittstelle, die die Namen der von der Benutzeroberfläche ausgegebenen Design-Token nach Art (Farbe, Länge, Zahl, Text) bereitstellt. ThemeDesignTokens implementiert dies im Kernmodul über die CSS-relevanten Einstellungen der klassischen Designs; UIThemeDesignTokens ersetzt es in com.top_logic.layout.react durch die Tokens der UI-Designs, so wie com.top_logic.element den CompatibilityService ersetzt. Ist eine Art nicht in der Registrierung enthalten, ist sie leer, und es wird dann nichts geprüft.
Die Prüfung und die Auswahl
ColorSpec#getToken() durchläuft diesen Dienst zweimal:
- Die Optionen. Die Farb-Tokens der Anwendung sind die Optionen der Eigenschaft, daher bietet der Modell-Editor anstelle eines Freitextfelds eine Dropdown-Liste mit den ausgegebenen Namen an. Ein Token, das die Anwendung nicht ausgibt, wird daneben beibehalten: Das Formular zeigt es an, und beim Speichern wird es unverändert zurückgeschrieben, sodass eine Anmerkung, die für ein Design geschrieben wurde, das die bearbeitende Anwendung nicht installiert, erhalten bleibt. Ein Name kann daher ausgewählt oder beibehalten, aber nicht neu eingegeben werden.
- Die Überprüfung. Ein Token, das von keinem Theme ausgegeben wird, wird als Warnung gemeldet, in der das Token sowie die ausgegebenen Namen genannt werden. DynamicModelService führt beim Start den ConstraintChecker über das gesamte geladene Modell aus, sodass eine Annotation in einer *.model.xml-Datei im Boot-Protokoll gemeldet wird und die Anwendung dennoch startet.
Es werden ausschließlich Farb-Token angeboten und akzeptiert – eine Pille, die mit „spacing-04“ oder „shadow-menu“ eingefärbt ist, ergibt keinen Sinn. Ein Design-Token benennt daher seine Art: „ThemeToken“ beantwortet dies und „UITheme“ behält es durch die Vererbungsauflösung bei. Ein Token, das ein anderes als Alias verwendet (<ref>), übernimmt den Typ des Tokens, das es benennt, und folgt dabei der Referenzkette sowie der Themenvererbung. Zwei stille Fehler dieses Mechanismus werden ebenfalls gemeldet: ein <ref>, das kein Token benennt, und ein Referenzzyklus.
Die klassischen Einstellungen tragen ihren Typ bereits in dem Tag, das sie schreibt.
support-info
Das React-Theme enthält „support-error“, „support-success“ und „support-warning“, jedoch keine „info“-Farbe, während das klassische Theme diese sehr wohl enthält – was dazu führte, dass die Annotation nicht funktionieren konnte. Die Familie wird durch „support-info“ vervollständigt, und in der Demo wird damit ein dritter Ticketstatus eingefärbt.
Nicht abgedeckt
Die Warnung wird im Modell-Editor nicht angezeigt – #29619. ConfigValidation wertet die Einschränkung aus und behält nur die Fehler bei, die keine Warnungen sind, da das, was es erfasst, die Anwendung des Formulars blockiert. Eine Einschränkung auf Warnungsniveau wird daher verworfen, obwohl das Feldsteuerelement der React-Benutzeroberfläche bereits einen „hasWarnings“-Zustand an den Client überträgt. Das Dropdown-Menü erschwert die Eingabe eines unbekannten Tokens von vornherein, sodass dort nur ein Token unberücksichtigt bleibt, das bereits gespeichert wurde.
Es gibt weiterhin zwei Registries. Ihre Vereinheitlichung ist eine Aufgabe für sich: Der klassische CSS-Name ist das letzte, durch einen Punkt getrennte Segment des Einstellungsnamens, und es sind Kollisionen möglich; die klassische Seite verfügt über eine zweite, in Java deklarierte Ebene (ThemeVar), und beide geben ihren Block zu unterschiedlichen Zeitpunkten aus (im generierten Stylesheet fest eingebunden vs. pro Anfrage geschrieben, begrenzt durch „data-theme“). Die Namensabweichungen, die der Vergleich aufzeigt – „support-error“ gegenüber „support-danger“, „layer-01“ gegenüber „layer“, „border-color“ gegenüber „border-subtle“ – bleiben unverändert.
Ein Modell, das anstelle der Konfiguration aus der Datenbank ausgelesen wird (DynamicModelService lädt die gespeicherten Annotationen), umgeht den ConstraintChecker vollständig; dieser Pfad meldet nichts, weder für diese Annotation noch für irgendeine andere Konfigurationsbeschränkung.