History: Pagetop Styles and CSS Variables

• «
• »

            {DIV(class="lead")}__Motivation for these changes: Find a better way to style Tiki's mix of top/topbar elements and often nested navbars.__{DIV}

!! The arrangement of Tiki's navbars
The standard Bootstrap navbar element is normally a single navbar and isn't used in combination with another one. On the other hand, Tiki's top and topbar elements evolved from pre-Bootstrap portal-style layouts. The way Bootstrap is implemented in Tiki's page-top elements often puts one navbar element inside another -- one for the entire module zone, and often one for a menu contained in a module in that module zone. If both navbars, the outer and inner one, have solid-color backgrounds, and it's the same color, then there's no problem with appearance. But if a gradient or image is specified for the background, then the navbar-on-navbar effect is obvious and usually unattractive. 

Even if there were just one navbar, but it was contained in one or more divs that have content in addition to the navbar, there would still be a styling problem to deal with, involving color consistency, borders, shadows, and so on, this area.

!! Navbar colors also applied to parent divs
Some time ago, the parent divs of a navbar in the top module zone were given CSS classes such as -+bg-light-parent+- or -+bg-dark-parent+- . When the color preference of the navbar is switched in Look & Feel Admin, the colors of these parent divs are also switched, along with the colors of the navbar they contain, with the thinking that this is the desired behavior to prevent a patchwork of colors in these zones. (Of course this can be overridden by custom CSS or a theme stylesheet if desired.) That was one step to coordinate pagetop color styling.

!! The basic idea of tiki-pagetop_colors.scss
Assuming the navbar's parent divs and the navbar have the same color scheme, to prevent "gradient-on-gradient" or "bordered box or box-shadowed box inside bordered box or box-shadowed box," with -+ tiki-pagetop_colors.scss+- , the styling is applied only to the topmost or outermost element, such as -+.navbar.fixed-top+- in the Basic Bootstrap layout, and then any nested -+ div.bg-*-parent+- and the navbar itself is give a transparent background and borders and box-shadows are given a -+none+- value. 

A caveat here: The assumption with this discussion is that a common background color or treatment is wanted for the entire top module zone or topbar module zone. In the case of a design where the module zone has one background color or gradient or image and a menu in that module zone has a different one, then theme designer shouldn't import -+ themes/base_files/scss/tiki-pagetop_colors +- . The purpose of the file is to make uniform the background and foreground colors of the relevant divs and enable easy modification of these properties.

I found myself repeatedly writing a lot of CSS to style these page elements, especially when linear gradients or images are used for backgrounds. [[Show example code.] I asked myself why do I need to do this for every theme with this type of color scheme? Not only aftermarket or custom themes but also some in the Tiki package like Darkroom and FiveAlive, and some Bootswatch themes lik Cerulean have potential "gradient on gradient" problems if special CSS isn't written to counteract it.
!! First step: tiki-pagetop_colors
I had earlier created an SCSS file for color-variant child themes like those in FiveAlive and FiveAlive-lite, to avoid having to write the same CSS color rules for each theme. I used the same idea for the pagetop colors file that could be used by any theme, and the color-variant child themes could also use this file. 

I made the file by collecting the "tiki-selectors" SCSS rules of themes that have relatively complex top and topbar zone color styles, and then simplified the rules, eliminating redundancies, and so on; initially this was just for background colors but then it was extended to cover background gradients and background images also. It addresses both top and topbar module zones (and parent divs) and both dark and light navbar options. (As of Bootstrap 5.2, the navbar-light/bg-light classes are retired, but are still used in Tiki unless there is a good reason to change.) 

!! Pagetop styles and CSS variables
As the -+tiki-pagetop_colors+- file was progressing, SCSS variables were used to set values for the properties, as with most of Tiki's theme files. But it was apparent that this would be a natural and very useful place to use CSS variables, which to be honest I was just starting to get a handle on, so this was really a learning experience for me. So I replaced the SCSS variables in this file with CSS variable equivalents, and found the location in the theme files to define the CSS variables. This was tested first with the Utopias theme and since then I'm working my way through the other themes.

!! Background info on CSS variables
{QUOTE()}
Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that contain specific values to be reused throughout a document. They are set using custom property notation (e.g., -+ ~np~--~/np~main-color: black;)+- and are accessed using the -+var()+- function (e.g., -+color: var(~np~--~/np~main-color);+- ).
-- [https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties]
{QUOTE}

!! CSS variables in Bootstrap
There were just 28 CSS variables in Bootstrap 4 ([https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables]).  As of Bootstrap 5.2, this number, for root CSS variables, is up to approximately 70 ([https://getbootstrap.com/docs/5.2/customize/css-variables/#root-variables]). Root CSS variables have global scope. There are also component variables, with narrow scope, such as those used for [https://getbootstrap.com/docs/5.2/content/tables/#how-do-the-variants-and-accented-tables-work|tables] and [https://getbootstrap.com/docs/5.2/components/navbar/#css|navbars]. (I just recently became aware of these navbar CSS variables, so will look again at the Tiki CSS variables implementation to try to be as coherent as possible.

!! The Tiki CSS variable syntax
Just a short time ago we realized it would be useful to distinguish SCSS variables created specifically for Tiki from Bootstrap or other SCSS variables, so we decided on the -+$tiki-+- prefix, following luci's suggestion. I used the same pattern for our CSS variables, using -+ --tiki- +-.  (The prepended two hyphens and appended single hyphen are the standard format for CSS variables.)

So far, for the pagetop colors, we have these Tiki CSS variables:
~pp~
~--tiki-top-bg-light
--tiki-top-light-colo
--tiki-top-light-link-color
--tiki-top-light-link-hover-color

--tiki-topbar-bg-light
--tiki-topbar-light-color
--tiki-topbar-light-link-color
--tiki-topbar-light-link-hover-color

--tiki-top-bg-dark
--tiki-top-dark-color
--tiki-top-dark-link-color
--tiki-top-dark-link-hover-color

--tiki-topbar-bg-dark
--tiki-topbar-dark-color
--tiki-topbar-dark-link-color
--tiki-topbar-dark-link-hover-color
~/pp~

As the docs on CSS variables show, they need to be presented in an array.]This array, in a theme's files, can/should be placed at the bottom of the theme's variables file. This positions the -+:root +- array at the beginning of the theme CSS file, where it needs to be, and also after the SCSS variables are defined, which CSS variables often require. This example is from FiveAlive/Orange:

{CODE(style="css")}
// CSS variables / custom properties for base_files/scss/_tiki-pagetop_colors.scss -- Interpolation info from https://developersink.com/css/css-custom-properties-sass-variables/
// Background images (actual images or CSS gradients, etc.), if assigned, override background colors.
:root {
    --tiki-top-bg-light: linear-gradient(to right,  #c44a23 0%,#c64b23 10%,#dc5823 34%,#e96023 58%,#f06423 87%,#f06423 100%);
    --tiki-top-light-color: #{$navbar-light-color};
    --tiki-top-light-link-color: #{$navbar-light-link-color};
    --tiki-top-light-link-hover-color: #{$navbar-light-link-hover-color};

    --tiki-topbar-bg-light: #{$topbar-light-color};
    --tiki-topbar-light-color: #{$topbar-light-color};
    --tiki-topbar-light-link-color: #{$navbar-light-link-color};
    --tiki-topbar-light-link-hover-color: #{$navbar-dark-link-hover-color};

    --tiki-top-bg-dark: linear-gradient(to right,  #c44a23 0%,#c64b23 10%,#dc5823 34%,#e96023 58%,#f06423 87%,#f06423 100%);
    --tiki-top-dark-color: #{$top-dark-color};
    --tiki-top-dark-link-color: #{$navbar-dark-link-color};
    --tiki-top-dark-link-hover-color: #{$navbar-dark-link-hover-color};

    --tiki-topbar-bg-dark:#{$topbar-dark-bg};
    --tiki-topbar-dark-color: #{$navbar-dark-color};
    --tiki-topbar-dark-link-color: #{$navbar-dark-link-color};
    --tiki-topbar-dark-link-hover-color: #{$navbar-dark-link-hover-color};
}
{CODE}

!! Look & Feel customization
To redefine one or more of the CSS variables, currently it works to input the variable name and the new value in the Look & Feel admin customization text area, inside the -+:root +- array.

This could also be in a custom.css file.

!! Future possibilities
* A dedicated Look & Feel "CSS Variables" text area provided so that just the variables could be entered and the root array syntax would be added on the backend.
* New Tiki CSS variables in addition to those for pagetop colors -- what other Tiki page elements should easy customization be enabled for?
* Site color controls (or other controls) available to site users on the public side, such as for dark mode, like switching themes but not needed a page refresh -- [https://pedromarquez.dev/blog/2022/7/dark-mode-css]

!! References:
* https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
* https://blog.getbootstrap.com/2022/05/16/using-bootstrap-css-vars/
* https://getbootstrap.com/docs/5.2/customize/css-variables/
* https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables
* https://pedromarquez.dev/blog/2022/7/dark-mode-css