major
minor
major
minor
major
#26986
Do not use theme variables directly but only via CSS variables
Developers can use Top-Logic theme variables in stylesheets (CSS files) by enclosing the variable name in percent signs: %TL_THEME_VARIABLE_NAME%.
When the application starts, all CSS files are merged to create a single, comprehensive file for each theme, in which the theme variables are replaced with their values. This is undesirable because it prevents users from using the browser console’s inspector to determine whether—and, if so, which—theme variables might be used at the location they are examining.
It is difficult to determine how the theme variables relate to parts of the layout.
Implementation
Instead of directly replacing theme variables with their values, CSS variables are used to allow users to use developer tools to determine which variables affect the part of the layout they’re examining.
For every theme variable `X` used in a CSS file, a CSS variable `--X: value` is defined with the value of the theme variable. The evaluation of the theme variable must be changed accordingly from `%X%` to `var(--X)`. The CSS variables are defined in the CSS selector `:root `.
Code Migration
- Search CSS files for the regular expression %([A-Za-z_][-A-Za-z_0-9\\.@/]*)% (pattern matching a theme variable name) and replace it with var(--$1).
- CSS variables cannot be used within ` url ` (details here). Unless the variables are explicitly used in the Java code, their type can be changed from `<ICON> ` to `<STRING>`, and their value can be wrapped in `url(...) ` in the corresponding definitions in ` theme-settings.xml`. Otherwise, new variables must be created. In the CSS files, the ` url(var(--foobar)) ` can then be replaced with `var(--foobar)` for the variable ` foobar`.
- Values of variables that are to be used for further calculations must be used within a CSS `calc` function. Expressions of the form `width: -var(--myWidth) ` are invalid. Instead, the expression ` width: calc(-1*var(--myWidth))` can be used. To identify such issues, the regular expression :\s*([^\s]+\s*var\(--[a-zA-Z_-]+\)|var\(--[a-zA-Z_-]+\)[^\s]+\s*)\s*; be used for CSS files. Not all search results indicate a problem, as there are also CSS shortcuts such as margin: 5px 10px, which set a margin for all sides.
- Dialog#createDialog has been removed.
- In LayoutUtils#createDialogInfo, the signature for width and height has been changed from int to tl:DisplayDimension.
- In tl:SizeInfo, the configuration options `widthUnit ` and `heightUnit` have been removed, and the type of `height ` and `width ` has been changed from `int ` to `tl:DisplayDimension`. Instead of, for example, configuring the width and height separately by specifying the value and unit in `tl:DialogInfo`, this is now done directly using `height ` and ` width `.
{{{#!xml <dialogInfo
height="100"
heightUnit="px"
width="50"
widthUnit="%"
/> }}} becomes: {{{#!xml <dialogInfo
height="100px"
width="50%"
/> }}}
- The templates
- editAttributedDialog.xml
- createAttributed.xml
- riskDialog.xml
- createAttributedNoSecLayout.xml
now have a unit for the width and height parameters.
- The tl:SortConfigDialog configuration for dialogs used to sort columns now only includes the options width and height (value with unit) instead of the options dialogWidth, dialogHeight, dialogWidthUnit, and dialogHeightUnit.
Test
Start the demo. Use the Inspector in the Developer Tools to examine parts of the layout within the application. You should be able to see the use of CSS variables. In particular, a large number of variables should be defined in the CSS selector :root.