Hide

YetaWF Documentation

Display
Print

CSS Custom Properties

Starting with YetaWF 5.4.0, CSS custom properties (a.k.a. CSS variables) are used to provide color and other CSS information for skins. This helps make components uniform and components are more easily customized to match any custom skin.

Usage

CSS Custom properties are always defined in a skin package, in one of the SCSS or CSS files used by the skin package. All properties must be defined in the :root element.

:root {
    // Page
    --body-bg: transparent; // the page default background color
    --body-clr: #{$std-clr}; // the page default text color

    // Sidebar elements (Page Bar, etc.)
    --bar-bg: #{$shaded-bg};
    --bar-clr: #{$shaded-clr};
    --bar-bg-hover: #{$shaded-bg-hover};
    --bar-clr-hover: #{$shaded-clr-hover};
    --bar-bg-active: #{$shaded-bg-active};
    --bar-clr-active: #{$shaded-clr-active};

    ...

    // Tabs
    --tabs-bg: #{$std-bg};
    --tabs-strip-bg: #{{darken($shaded-bg, 5%)}};
    --tabs-strip-border-width: #{$std-border-width};
    --tabs-strip-border-radius: #{$std-border-radius};
    --tabs-tab-bg: #{$shaded-bg};
    --tabs-tab-clr: #{$shaded-clr};
    --tabs-tab-bg-hover: #{$shaded-bg-hover};
    --tabs-tab-clr-hover: #{$shaded-clr-hover};
    --tabs-tab-bg-active: #{$shaded-bg-active};
    --tabs-tab-clr-active: #{$shaded-clr-active};
    --tabs-tab-border-color: #{$shaded-border-clr};
    --tabs-tab-border-width: #{$std-border-width};
    --tabs-tab-border-radius: #{$std-border-radius};
}

Any .scss or .css files that are part of YetaWF (not external files or in ./node_modules) can contain CSS variables. When using fallbacks in var(--variable, fallback), the fallback value is lost. If a variable doesn't exist (which should not happen), the var() expression remains unchanged. During startup, while creating CSS files for legacy browsers, any CSS variables that are used in any CSS files, but have not been defined, will cause an error message to be generated.

Themes

Each skin can define multiple themes. These are collections of files in the skin's ./product-name/_Skins/skin-name/Themes folder. Each file contains a set of CSS variables typically generated by the Skin Palette.

Themes can provide customize SVG images, overriding SVG images used by packages. To override a package's SVG image, add the image to the skin's SVG folder using the following naming convention:

area-name_image-name.svg

For example, the image fas-arrows.svg used by the Text package can be overridden with a file named "YetaWF_Text_fas-arrows.svg" in the skin's SVG folder.

Skin Palette

Using the Skin Palette, the current theme can be modified and saved (except for the Default theme). Any such themes can be selected in Control Panel > Skins tab, Theme selection. The Skin Palette is only available in non-deployed builds (i.e., a development system) and must be enabled as a module reference in Admin > Settings > Site Settings, References tab, enabling the Skin Palette (Skin) module.

Legacy Browsers

Older browsers, mainly Internet Explorer 11 and older, don't support CSS custom properties. To work around their limitations, YetaWF automatically creates CSS files without CSS custom properties. This generally results in identical rendering of components.

Legacy browsers can't use skin themes and only the Default theme is used when rendering pages for legacy browsers.

YetaWF currently only identifies IE 11 and older as legacy browsers. We may expand this in the future as needed.

All legacy support CSS files are generated in the following folder:

./wwwroot/_L/skinname/url

When a CSS file at url is requested by a legacy browser, the file at ./wwwroot/_L/skinname/url is served instead. The files in this folder do not use any CSS custom properties. All var(...) expressions are replaced by the defined values.

Opt Out

By default, legacy browser support is enabled. Sites can opt out of legacy browser support altogether by defining the following setting in AppSettings.json.

{
    "Application": {
        "P": {
            "YetaWF_Core": {
                "SupportLegacyBrowser": false
            }
        }
    }
}

When legacy browser support is disabled, legacy browsers will be redirected to a page showing that the browser is not supported. The page shown can be defined using Admin > Settings > Site Settings, URLs tab, Unsupported Browsers URL field (standard YetaWF site).

Disabling legacy browser support should be carefully considered. Some bots use User Agent strings which identify them as legacy browsers. You may or may not want to prevent these bots from accessing your site. And, there may always be that occasional user that still uses IE 11, or 10.

But Why?

It may seem that YetaWF could build all legacy CSS in the build pipeline rather than during startup. Unfortunately, that is not possible because legacy CSS for each available skin has to be created. Skins are not readily available at build time and skin discovery would unnecessarily complicate the build pipeline.

Building the legacy CSS during startup does slow down startup by at most 1-2 seconds. When using Blue/Green deployment this has no impact on the running site. Switchover happens after startup has completed so only deployment is slowed down by a few seconds. The impact will become apparent when Blue/Green deployment is not used. For new sites, disabling legacy browser support is recommended.

This legacy support will be expanded in the future to include JavaScript and possibly other CSS features, as they are added to YetaWF. YetaWF wants to take advantage of new technology without being too restrictive on legacy browsers that are still in more than occasional use. At this time, even Internet Explorer 11 still has a >3% use (1/1/2021). We pity the users that suffer its slow performance.