GH-191: Theme (for ProTX Light Header & TACC Blue Header)

[wesleyboar]

Status

• 2021-04-27: No rush to do, because ProTX runs on an image with it.
• 2021-05-12: Need to do, so env variables are available for Header Redesign → FP-1458 #101.
• 2021-09-03: [ same status | improved "To Do" list ]
• 2021-09-21: Begin update to use new CMS settings setup.

To Do

Done

• Use .env. ¹
• Use secrets.pysettings_custom.py.²
• Wait for https://github.com/TACC/protx/ to be updated. ³
• Update PR screenshots. ⁴
• Record future research tasks.⁵

Footnotes

1. Use Old Theme Management Code

• Distinguish theme via .env file value. 396c018 changes this to use secrets.py.

2. Use New Theme Management Code

• 396c018* Import THEME from settings.py instead of .env.
• Update PR desc based on 396c018* changes.
• Update Jenkins config based on 396c018* changes.
• Test deploy with THEME change.
  • Pending ability to deploy. Options:
    • sudo access on server using Camino-based deploy
      • ⊗ request for access to a server RT-19490
      • ⊗ server and access but no deploy RT-19292
      • → support to deploy to dev.cepcms; options:
        • FP-1184
        • FP-1120
        • FP-1136
    • Separate Custom Settings From Secrets #39

3. TACC/ProTX Out of Date

0. ProTX Portal is from TACC/proTX.
1. https://pprd.protx.tacc.utexas.edu/core/markup/nav returns 404
2. CMS expects markup from /core/markup/nav via https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/templates/nav_portal.html#L16
3. Portal should load template nav_portal.raw.html via https://github.com/TACC/Core-Portal/blob/main/server/portal/urls.py#L52
4. https://github.com/TACC/protx/tree/main/server/portal/templates/includes is missing nav_portal.raw.html (added 5 months ago at 64e93ef)

4. Merged by Tester out of Urgency

Screenshots not updated, but code was deployed and testable.

The ProTX (Pre-Prod) use case—which I allowed to delay updated screenshots—had an issue that was related to Portal code, not CMS code. Tester did not need updated screenshots.

5. Research Tasks

• How will this work for blue header for TACC redesign? Support Colored Header (TACC Blue Header) #349
• Consider using env() for fonts so we can remove import of global font vars that is redundant on Portal. https://github.com/TACC/Core-CMS/blob/3157107/taccsite_cms/static/site_cms/css/src/site.header.css#L13-L14

Overview

1. Support a light navbar for dark logo via:
   • env() variables
   • THEME in secrets
2. Use CSS color variables in header and footer.
3. Fix related bugs and comments.

Issues

• Themes via Settings (Light Header Navbar) #191

Changes

• document solution
• use new env() variables* to apply theme
• allow Node to read Python settings

(complete changelog)

• Doc: Explain .env file via new .env.sample.
• Minor: Git Ignore settings.json.
• Doc: Mention new .env.sample in README.
• New: Support native* built-time variables a.k.a. env() variables*.
• New: Auto-run settings_to_json.py before npm run build.
• Minor: Add Python utility script to hide python print statements.
• New: Add _THEME to secrets/settings.
• New: New Python script to export select secrets/settings to JSON.
• New: Apply theme via env() variables* and dark logo.
• Minor: Fix relevant search bar Bootstrap form control style bug.
• New: Improve comment in site.header.css.
• Doc: Explain document assets needed by Portal and Doc.

* Are these .env variables a widely-supported web standard?

• Usage, yes. It has already been supported in all modern browsers.
• Assignment, no. We use a polyfill postcss-env-function (via postcss-preset-env).

Testing

Last recorded deploys:

• ProTX (Pre-Prod) with THEME has-dark-logo
• Core (Dev) with no THEME (deploy #175)
• ⊗ ProTX (Pre-Prod) with THEME has-dark-logo
  • ✓ build
  • ✓ update secrets for newer CMS code
  • ✓ deploy
  • ⊗ CMS pages can not load portal nav
  • … deploy newer Portal

Test that these _THEME values do not crash and result in the expected header theme:

• no entry — default (dark header) theme
• no value — default (dark header) theme
• has-dark-logo — new light header theme
• default — default (dark header) theme
• bob — unable to build CSS

Detailed Walkthrough

No Theme — Default

1. Do not add THEME to secrets.py.
2. (if testing locally) Run npm run build.
3. See no errors.
4. Load CMS to watch it build "default theme" (imperceptible style change).
   • This tests THEME is not required.
   • This tests the "default" THEME as a fallback.
   • This tests env() variables.
   • This tests minor style changes.

Empty Theme i.e. Default

1. Do add THEME setting with None value.
2. (if testing locally) Run npm run build.
3. See no errors.
4. Restart CMS and load page to see same "default theme".
   • This tests THEME may be empty.
   • This tests the "default" THEME as a fallback.
   • This tests env() variables.
   • This tests minor style changes.

has-dark-logo Theme

1. Now change THEME setting to has-dark-logo.
2. (if testing locally) Run npm run build.
3. See no errors.
4. Reload CMS page to see light (for ProTX) header.
   • This tests THEME works with known value.
   • This tests env() variables.

default Theme

1. Now change THEME setting to default.
2. (if testing locally) Run npm run build.
3. See no errors.
4. Reload CMS page to see dark (default) header.
   • This tests the "default" THEME as a choice.
   • This tests THEME works with known value.
   • This tests env() variables.

Unknown THEME i.e. Failure

1. Now change THEME setting to bob.
2. (if testing locally) Run npm run build.
3. See error(s).
   • This tests the "default" THEME as a choice.
   • This tests THEME fails with unknown value.
   • This tests THEME works with known value.
   • This tests env() variables.

Screenshots

CMS (Might be Out of Date)

Light Navbar For Dark Logo

Dark Navbar For Most Logos

Notes

1. Does Not Implement New Header Design

   New header design comes via GH-101/FP-1458: Header Redesign #222, which relies on this PR.

[wesleyboar]

Instead of having CSS's runtime variables (custom properties) use build-time variables to result in baking in the THEME styles. Thus, Portal and User Guide need not load any script nor access any API.

[wesleyboar]

When I un-pause this PR, I will re-open it.

[wesleyboar]

Un-pausing. #222 both needs this and should be finished this year.

[wesleyboar]

Notes for Reviewers

[taoteg]

Built and ran locally using this branch and all worked as expected.