From 6e7322813d1756ffc94836c83cb06e7c4925d852 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 6 Jan 2025 02:03:44 -0800 Subject: [PATCH 1/3] Reorganize Classic UI Theming part --- docs/backend/schemas.md | 1 - docs/classic-ui/theming/barceloneta.md | 347 ------------------ .../theming/{color-mode.md => color-modes.md} | 10 +- docs/classic-ui/theming/create-add-on.md | 143 ++++++++ .../theming/css-custom-properties.md | 143 ++++++++ docs/classic-ui/theming/diazo.md | 19 - docs/classic-ui/theming/from-scratch.md | 199 ---------- docs/classic-ui/theming/index.md | 32 +- docs/classic-ui/theming/scss-structure.md | 74 ++++ docs/classic-ui/theming/settings-ttw.md | 62 ++++ docs/classic-ui/theming/through-the-web.md | 78 ---- 11 files changed, 450 insertions(+), 658 deletions(-) delete mode 100644 docs/classic-ui/theming/barceloneta.md rename docs/classic-ui/theming/{color-mode.md => color-modes.md} (91%) create mode 100644 docs/classic-ui/theming/create-add-on.md create mode 100644 docs/classic-ui/theming/css-custom-properties.md delete mode 100644 docs/classic-ui/theming/diazo.md delete mode 100644 docs/classic-ui/theming/from-scratch.md create mode 100644 docs/classic-ui/theming/scss-structure.md create mode 100644 docs/classic-ui/theming/settings-ttw.md delete mode 100644 docs/classic-ui/theming/through-the-web.md diff --git a/docs/backend/schemas.md b/docs/backend/schemas.md index 1e519d953..24bc654a1 100644 --- a/docs/backend/schemas.md +++ b/docs/backend/schemas.md @@ -101,7 +101,6 @@ This schema can be used in {doc}`/classic-ui/forms` and Dexterity {doc}`/backend ```{note} In Dexterity {doc}`/backend/content-types/index`, the base class for a schema is `plone.supermodel.model.Schema`. -This provides functionalities to export and import schemas via XML and the {doc}` Through-the-web (TTW) ` editor. ``` diff --git a/docs/classic-ui/theming/barceloneta.md b/docs/classic-ui/theming/barceloneta.md deleted file mode 100644 index 18c767c81..000000000 --- a/docs/classic-ui/theming/barceloneta.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Classic UI theming based on Barceloneta" - "property=og:description": "Plone Classic UI theming based on Barceloneta" - "property=og:title": "Plone Classic UI theming based on Barceloneta" - "keywords": "Plone, Classic UI, theming, Barceloneta" ---- - -(classic-ui-theming-barceloneta-label)= - -# Classic UI theming based on Barceloneta - -This chapter describes how to create a custom theme for Plone Classic UI based on Barceloneta. -Barceloneta is the default enabled theme for Plone Classic UI. - - -(classic-ui-theming-barceloneta-prerequisites-label)= - -## Prerequisites - -To create an add-on package with a Plone Classic UI theme, you need to install the following prerequisites. - -- [Node.js (16/18)](https://nodejs.org/en) -- [Python (>=3.8)](https://www.python.org/) -- [plonecli](https://pypi.org/project/plonecli/) - - -(classic-ui-theming-barceloneta-create-a-classic-ui-theme-add-on-package-label)= - -## Create a Classic UI theme add-on package - -To create a Classic UI theme add-on, begin with the following command. - -```shell -plonecli create addon plonetheme.themebasedonbarceloneta -``` - -Then change the working directory into the package you just created, and add the basic theme structure with the following commands. - -```shell -cd plonetheme.themebasedonbarceloneta -plonecli add theme_barceloneta -``` - -Give your theme a name, and optionally commit the changes. -After that, the theming structure is set up and ready for customization. -You can create a Plone Site and install your theme add-on in the controlpanel. - - -(classic-ui-theming-barceloneta-theme-structure-label)= - -## Theme structure - -All the theming relevant files are now located inside `src/plonetheme/themebasedonbarceloneta/theme/`: - -```text -./src/plonetheme/themebasedonbarceloneta/theme/ -├── barceloneta-apple-touch-icon-114x114-precomposed.png -├── barceloneta-apple-touch-icon-144x144-precomposed.png -├── barceloneta-apple-touch-icon-57x57-precomposed.png -├── barceloneta-apple-touch-icon-72x72-precomposed.png -├── barceloneta-apple-touch-icon-precomposed.png -├── barceloneta-apple-touch-icon.png -├── barceloneta-favicon.ico -├── index.html -├── manifest.cfg -├── package.json -├── preview.png -├── rules.xml -├── scss -│ ├── _custom.scss -│ ├── _maps.scss -│ ├── _variables.scss -│ └── theme.scss -├── styles -│ ├── theme.css -│ └── theme.min.css -└── tinymce-templates - ├── README.rst - ├── card-group.html - └── list.html -``` - -`index.html` -: Basic HTML structure for the site layout. - -`manifest.cfg` -: Basic theme configuration for the backend. - -`package.json` -: npm package configuration which defines all requirements for theming with barceloneta. - -`rules.xml` -: Diazo rules which translate the `index.html` and fills it with content from the backend. - -`scss/_custom.scss` -: Custom SCSS rules for your theme. - -`scss/_maps.scss` -: Override Bootstrap mapping variables here. - -`scss/_variables.scss` -: Override Bootstrap and/or Barceloneta variables here. - -`scss/theme.scss` -: Base theme file which follows "Option B" of customizing Bootstrap imports to enable custom variable and map injections. - Note that the order of these imports is mandatory to ensure overriding the defaults. - See https://getbootstrap.com/docs/5.3/customize/sass/#importing. - -`styles/theme.css[.min]` -: Compiled CSS styles. - -`tinymce-templates/*.html` -: HTML snippets for the TinyMCE `template` plugin. - - -(classic-ui-theming-barceloneta-compiling-theme-resources-label)= - -## Compiling theme resources - -To compile the SCSS code, you have to install the required dependencies with `npm`. -Then run the package script `build` inside the `theme/` folder: - -```shell -npm install -npm run build -``` - -During theme development, you can run: - -```shell -npm run watch -``` - -This compiles the SCSS resources on the fly when you change something inside the `scss/` folder. -You can preview your changes when you reload your browser. - - -(classic-ui-theming-barceloneta-customize-components-label)= - -## Customize Bootstrap and Barceloneta components - -The base `scss/theme.scss` file provides all imports of the dependent Bootstrap and Barceloneta resources to build the default Classic UI theme. -As a convenience `bobtemplates.plone` has created three files to customize variables, maps, and custom SCSS code. - -```text -scss/_custom.scss -scss/_maps.scss -scss/_variables.scss -``` - - -(classic-ui-theming-barceloneta-scss-and-root-variables-label)= - -### SCSS and root variables - -To set a custom font, you define the font variables in `scss/_variables.scss`: - -```scss -$font-family-sans-serif: Tahoma, Calimati, Geneva, sans-serif; -$font-family-serif: Georgia, Norasi, serif; -``` - -This will override the default values from Barceloneta. - - -### SCSS and properties - -The following example shows how to disable rounded corners for borders. - -```scss -$enabled-rounded: false; -``` - -A complete list of all properties see {ref}`classic-ui-theming-barceloneta-default-variables-and-properties-label`. - - -(classic-ui-theming-barceloneta-maps-label)= - -### Maps - -Maps are key/value pairs to make CSS generation easier. -As an example, the following example shows the workflow colors map: - -```scss -$state-colors: ( - "draft": $state-draft-color, - "pending": $state-pending-color, - "private": $state-private-color, - "internal": $state-internal-color, - "internally-published": $state-internally-published-color, -) !default; -``` - -If you have a custom workflow state, you can add your state color to the default map in `scss/_maps.scss` as shown below. - -```scss -$custom-state-colors: ( - "my-custom-state-id": "#ff0000" -); - -// Merge the maps -$state-colors: map-merge($state-colors, $custom-colors); -``` - -(classic-ui-theming-barceloneta-custom-css-code-label)= - -### Custom CSS code - -Inside the file `theme/_custom.scss` you can write all your custom CSS/Sass code to adapt the theme to your needs. -Feel free to add more files inside the `scss/` folder to make your code more readable. -Don't forget to import your custom files in `scss/theme.scss`. - - -(classic-ui-theming-barceloneta-default-variables-and-properties-label)= - -## Default variables and properties - -The following variables and properties are defined in Bootstrap and customized by Barceloneta. - -### Component variables - -```scss -// Barceloneta settings - -$primary: $plone-link-color!default; -$light: $plone-light-color!default; -$dark: $plone-dark-color!default; - -$spacer: 1rem!default; // not changed but needed to calc other definitions - - -// Grid columns -// Set the number of columns and specify the width of the gutters. - -// $grid-columns: 12 !default; -// $grid-gutter-width: 1.5rem !default; -// $grid-row-columns: 6 !default; - -$grid-main-breakpoint: lg!default; -$nav-main-breakpoint: $grid-main-breakpoint!default; - -$navbar-barceloneta-background: $primary!default; - -$navbar-padding-y: 0 !default; -$navbar-padding-x: 0 !default; -$navbar-nav-link-padding-y: $spacer * .75 !default; -$navbar-nav-link-padding-x: $spacer !default; - -$navbar-light-color: rgba($black, .55) !default; -$navbar-light-active-color: rgba($black, .7) !default; -$navbar-light-active-background: rgba($black, .2) !default; -$navbar-light-hover-color: rgba($black, .9) !default; -$navbar-light-hover-background: rgba($black, .3) !default; - -$navbar-dark-color: rgba($white, 1) !default; -$navbar-dark-active-color: rgba($white, 1) !default; -$navbar-dark-active-background: rgba($white, .2) !default; -$navbar-dark-hover-color: rgba($white, 1) !default; -$navbar-dark-hover-background: rgba($white, .3) !default; - -$navbar-barceloneta-color: rgba($white, 1) !default; -$navbar-barceloneta-active-color: rgba($white, 1) !default; -$navbar-barceloneta-active-background: rgba($black, .2) !default; -$navbar-barceloneta-hover-color: rgba($white, 1) !default; -$navbar-barceloneta-hover-background: rgba($black, .3) !default; - - -$plone-portlet-navtree-maxlevel: 5!default; - - -// Typography -// While Plone Logo uses the DIN Font, we use Roboto, which was designed for Android and so mobile optimized -// A free DIN variant is available here (TTF only): https://www.1001fonts.com/alte-din-1451-mittelschrift-font.html -$font-family-sans-serif: "Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif!default; -$font-family-condensed: "Roboto Condensed", "Arial Narrow", sans-serif!default; //just on toolbar -$font-family-serif: Georgia, "Times New Roman", Times, serif!default; -// $font-family-base: var(--bs-font-sans-serif) !default; -// $font-family-code: var(--bs-font-monospace) !default; - -// Include Roboto as webfont -$enable-roboto-webfont: true !default; - -// $font-size-base: 1rem !default; // Assumes the browser default, typically `16px` -// $font-size-sm: $font-size-base * .875 !default; -// $font-size-lg: $font-size-base * 1.25 !default; - -$font-weight-lighter: lighter !default; -$font-weight-light: 300 !default; -$font-weight-normal: 400 !default; -$font-weight-semibold: 600 !default; -$font-weight-bold: 700 !default; -$font-weight-bolder: bolder !default; - -// $font-weight-base: $font-weight-normal !default; - -// $line-height-base: 1.5 !default; -// $line-height-sm: 1.25 !default; -// $line-height-lg: 2 !default; - -// $h1-font-size: $font-size-base * 2.5 !default; -// $h2-font-size: $font-size-base * 2 !default; -// $h3-font-size: $font-size-base * 1.75 !default; -// $h4-font-size: $font-size-base * 1.5 !default; -// $h5-font-size: $font-size-base * 1.25 !default; -// $h6-font-size: $font-size-base !default; - -// $headings-margin-bottom: $spacer * .5 !default; -// $headings-font-family: null !default; -// $headings-font-style: null !default; -$headings-font-weight: $font-weight-normal !default; -// $headings-line-height: 1.2 !default; -// $headings-color: null !default; - -// Breadcrumbs -$breadcrumb-margin-bottom: 2rem !default; -$breadcrumb-bg: var(--bs-secondary-bg) !default; -$breadcrumb-padding-y: $spacer * 0.5 !default; -$breadcrumb-padding-x: $spacer * 1 !default; - - -// Footer -$footer-bg: $gray-900 !default; -$footer-color: $gray-300 !default; -``` - -### Properties - -```scss -$enable-caret: true !default; -$enable-rounded: true !default; -$enable-shadows: false !default; -$enable-gradients: false !default; -$enable-transitions: true !default; -$enable-reduced-motion: true !default; -$enable-smooth-scroll: true !default; -$enable-grid-classes: true !default; -$enable-container-classes: true !default; -$enable-cssgrid: false !default; -$enable-button-pointers: true !default; -$enable-rfs: true !default; -$enable-validation-icons: true !default; -$enable-negative-margins: true !default; -$enable-deprecation-messages: true !default; -$enable-important-utilities: false !default; -``` diff --git a/docs/classic-ui/theming/color-mode.md b/docs/classic-ui/theming/color-modes.md similarity index 91% rename from docs/classic-ui/theming/color-mode.md rename to docs/classic-ui/theming/color-modes.md index e50b24d63..c8bf46d35 100644 --- a/docs/classic-ui/theming/color-mode.md +++ b/docs/classic-ui/theming/color-modes.md @@ -7,7 +7,7 @@ myst: "keywords": "Plone, Classic UI, theming, color modes, Bootstrap, Twitter" --- -(color-modes-label)= +(classic-ui-theming-color-modes-label)= # Color modes @@ -24,8 +24,8 @@ This chapter is a guide for how to implement color modes in Plone 6. ## Preferred color modes You will need to add some JavaScript functionality to set the Bootstrap theme to the user's preferred color scheme. -Add the JavaScript file to the `browser/static` folder of your Plone 6 project. -Register it in the `browser/profiles/default/registry` of your Plone 6 project. +Add the JavaScript file to the {file}`browser/static` folder of your Plone 6 project. +Register it in the {file}`browser/profiles/default/registry` of your Plone 6 project. See {ref}`classic-ui-static-resources-registering-label` for more information. ```js @@ -75,8 +75,8 @@ If you want to add a theme toggler to your site, you can use the following examp You will need to add some JavaScript functionality to the toggler. The following code snippet is based on the [Bootstrap 5.3 documentation](https://getbootstrap.com/docs/5.3/customize/color-modes/#javascript). -Add the JavaScript file to the `browser/static` folder of your Plone 6 project. -Register it in the `browser/profiles/default/registry` of your Plone 6 project. +Add the JavaScript file to the {file}`browser/static` folder of your Plone 6 project. +Register it in the {file}`browser/profiles/default/registry` of your Plone 6 project. See {ref}`classic-ui-static-resources-registering-label` for more information. ```js diff --git a/docs/classic-ui/theming/create-add-on.md b/docs/classic-ui/theming/create-add-on.md new file mode 100644 index 000000000..6aba6f935 --- /dev/null +++ b/docs/classic-ui/theming/create-add-on.md @@ -0,0 +1,143 @@ +--- +myst: + html_meta: + "description": "Create a Classic UI theme add-on for Plone" + "property=og:description": "Create a Classic UI theme add-on for Plone" + "property=og:title": "Create a Classic UI theme add-on for Plone" + "keywords": "Plone, Classic UI, theming, add-on" +--- + +(classic-ui-create-a-theme-add-on-label)= + +# Create a theme add-on + +This chapter describes how to create a custom theme add-on for Plone Classic UI. + +You can install your theme add-on in the {guilabel}`Add-ons` control panel. +Theme add-ons are a convenient way to design once, then deploy with minimal effort everywhere. + + +## Prerequisites + +To create an add-on package with a Plone Classic UI theme, you need to install the following prerequisites. + +- [Node.js (16/18)](https://nodejs.org/en) +- [Python (>=3.8)](https://www.python.org/) +- [plonecli](https://pypi.org/project/plonecli/) + + +## Create a Classic UI theme add-on package + +To create a Classic UI theme add-on, begin with the following command. + +```shell +plonecli create addon plonetheme.themebasedonbarceloneta +``` + +Then change the working directory into the package you just created, and add the basic theme structure with the following commands. + +```shell +cd plonetheme.themebasedonbarceloneta +plonecli add theme_barceloneta +``` + +Give your theme a name, and optionally commit the changes. +After that, the theming structure is set up and ready for customization. + +```{seealso} +{doc}`scss-structure` +``` + +(classic-ui-theming-compile-theme-resources-label)= + +## Compile theme resources + +To compile the SCSS code, you have to install the required dependencies with `npm`. +Then run the package script `build` inside the {file}`theme/` folder. + +```shell +npm install +npm run build +``` + +During theme development, you can automatically compile SCSS resources when you change something inside the {file}`scss/` folder. +You can also preview your changes when you reload your browser. +To do so, run the following command. + +```shell +npm run watch +``` + + +(classic-ui-theming-customize-components-label)= + +## Customize Bootstrap components + +The base {file}`scss/theme.scss` file provides all imports of the dependent Bootstrap resources to build the default Classic UI theme. +As a convenience `bobtemplates.plone` has created three files to customize variables, maps, and custom SCSS code. + +- {file}`scss/_custom.scss` +- {file}`scss/_maps.scss` +- {file}`scss/_variables.scss` + + +(classic-ui-theming-scss-and-root-variables-label)= + +### SCSS and root variables + +To set a custom font, you define the font variables in {file}`scss/_variables.scss` as shown. + +```scss +$font-family-sans-serif: Tahoma, Calimati, Geneva, sans-serif; +$font-family-serif: Georgia, Norasi, serif; +``` + +This will override the default values from Classic UI. + + +### SCSS and properties + +The following example shows how to disable rounded corners for borders. + +```scss +$enabled-rounded: false; +``` + +See a complete reference list of Classic UI's {doc}`css-custom-properties`. + + +(classic-ui-theming-maps-label)= + +### Maps + +Maps are key/value pairs to make CSS generation easier. +As an example, the following example shows the workflow colors map. + +```scss +$state-colors: ( + "draft": $state-draft-color, + "pending": $state-pending-color, + "private": $state-private-color, + "internal": $state-internal-color, + "internally-published": $state-internally-published-color, +) !default; +``` + +If you have a custom workflow state, you can add your state color to the default map in {file}`scss/_maps.scss` as shown below. + +```scss +$custom-state-colors: ( + "my-custom-state-id": "#ff0000" +); + +// Merge the maps +$state-colors: map-merge($state-colors, $custom-colors); +``` + +(classic-ui-theming-custom-css-code-label)= + +### Custom CSS code + +Inside the file `theme/_custom.scss` you can write all your custom CSS/Sass code to adapt the theme to your needs. +Feel free to add more files inside the `scss/` folder to make your code more readable. +Don't forget to import your custom files in `scss/theme.scss`. diff --git a/docs/classic-ui/theming/css-custom-properties.md b/docs/classic-ui/theming/css-custom-properties.md new file mode 100644 index 000000000..67059a738 --- /dev/null +++ b/docs/classic-ui/theming/css-custom-properties.md @@ -0,0 +1,143 @@ +--- +myst: + html_meta: + "description": "Create a Classic UI theme add-on for Plone" + "property=og:description": "Create a Classic UI theme add-on for Plone" + "property=og:title": "Create a Classic UI theme add-on for Plone" + "keywords": "Plone, Classic UI, theming, add-on" +--- + +(classic-ui-theming-CSS-custom-properties-label)= + +# CSS custom properties + +This chapter describes the [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) used in Bootstrap and customized by Classic UI themes. +Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that represent specific values to be reused throughout a document. + + +## Component variables + +```scss +// Barceloneta settings + +$primary: $plone-link-color!default; +$light: $plone-light-color!default; +$dark: $plone-dark-color!default; + +$spacer: 1rem!default; // not changed but needed to calc other definitions + + +// Grid columns +// Set the number of columns and specify the width of the gutters. + +// $grid-columns: 12 !default; +// $grid-gutter-width: 1.5rem !default; +// $grid-row-columns: 6 !default; + +$grid-main-breakpoint: lg!default; +$nav-main-breakpoint: $grid-main-breakpoint!default; + +$navbar-barceloneta-background: $primary!default; + +$navbar-padding-y: 0 !default; +$navbar-padding-x: 0 !default; +$navbar-nav-link-padding-y: $spacer * .75 !default; +$navbar-nav-link-padding-x: $spacer !default; + +$navbar-light-color: rgba($black, .55) !default; +$navbar-light-active-color: rgba($black, .7) !default; +$navbar-light-active-background: rgba($black, .2) !default; +$navbar-light-hover-color: rgba($black, .9) !default; +$navbar-light-hover-background: rgba($black, .3) !default; + +$navbar-dark-color: rgba($white, 1) !default; +$navbar-dark-active-color: rgba($white, 1) !default; +$navbar-dark-active-background: rgba($white, .2) !default; +$navbar-dark-hover-color: rgba($white, 1) !default; +$navbar-dark-hover-background: rgba($white, .3) !default; + +$navbar-barceloneta-color: rgba($white, 1) !default; +$navbar-barceloneta-active-color: rgba($white, 1) !default; +$navbar-barceloneta-active-background: rgba($black, .2) !default; +$navbar-barceloneta-hover-color: rgba($white, 1) !default; +$navbar-barceloneta-hover-background: rgba($black, .3) !default; + + +$plone-portlet-navtree-maxlevel: 5!default; + + +// Typography +// While Plone Logo uses the DIN Font, we use Roboto, which was designed for Android and so mobile optimized +// A free DIN variant is available here (TTF only): https://www.1001fonts.com/alte-din-1451-mittelschrift-font.html +$font-family-sans-serif: "Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif!default; +$font-family-condensed: "Roboto Condensed", "Arial Narrow", sans-serif!default; //just on toolbar +$font-family-serif: Georgia, "Times New Roman", Times, serif!default; +// $font-family-base: var(--bs-font-sans-serif) !default; +// $font-family-code: var(--bs-font-monospace) !default; + +// Include Roboto as webfont +$enable-roboto-webfont: true !default; + +// $font-size-base: 1rem !default; // Assumes the browser default, typically `16px` +// $font-size-sm: $font-size-base * .875 !default; +// $font-size-lg: $font-size-base * 1.25 !default; + +$font-weight-lighter: lighter !default; +$font-weight-light: 300 !default; +$font-weight-normal: 400 !default; +$font-weight-semibold: 600 !default; +$font-weight-bold: 700 !default; +$font-weight-bolder: bolder !default; + +// $font-weight-base: $font-weight-normal !default; + +// $line-height-base: 1.5 !default; +// $line-height-sm: 1.25 !default; +// $line-height-lg: 2 !default; + +// $h1-font-size: $font-size-base * 2.5 !default; +// $h2-font-size: $font-size-base * 2 !default; +// $h3-font-size: $font-size-base * 1.75 !default; +// $h4-font-size: $font-size-base * 1.5 !default; +// $h5-font-size: $font-size-base * 1.25 !default; +// $h6-font-size: $font-size-base !default; + +// $headings-margin-bottom: $spacer * .5 !default; +// $headings-font-family: null !default; +// $headings-font-style: null !default; +$headings-font-weight: $font-weight-normal !default; +// $headings-line-height: 1.2 !default; +// $headings-color: null !default; + +// Breadcrumbs +$breadcrumb-margin-bottom: 2rem !default; +$breadcrumb-bg: var(--bs-secondary-bg) !default; +$breadcrumb-padding-y: $spacer * 0.5 !default; +$breadcrumb-padding-x: $spacer * 1 !default; + + +// Footer +$footer-bg: $gray-900 !default; +$footer-color: $gray-300 !default; +``` + +## Properties + +```scss +$enable-caret: true !default; +$enable-rounded: true !default; +$enable-shadows: false !default; +$enable-gradients: false !default; +$enable-transitions: true !default; +$enable-reduced-motion: true !default; +$enable-smooth-scroll: true !default; +$enable-grid-classes: true !default; +$enable-container-classes: true !default; +$enable-cssgrid: false !default; +$enable-button-pointers: true !default; +$enable-rfs: true !default; +$enable-validation-icons: true !default; +$enable-negative-margins: true !default; +$enable-deprecation-messages: true !default; +$enable-important-utilities: false !default; +``` diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md deleted file mode 100644 index fa0e4a864..000000000 --- a/docs/classic-ui/theming/diazo.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Classic UI theming with Diazo" - "property=og:description": "Plone Classic UI theming with Diazo" - "property=og:title": "Plone Classic UI theming with Diazo" - "keywords": "Plone, Classic UI, theming, Diazo" ---- - -(classic-ui-theming-diazo-label)= - -# Classic UI theming with Diazo - -```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1645 -``` - -Theming based on Diazo. diff --git a/docs/classic-ui/theming/from-scratch.md b/docs/classic-ui/theming/from-scratch.md deleted file mode 100644 index ad614d84d..000000000 --- a/docs/classic-ui/theming/from-scratch.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Classic UI theming from scratch" - "property=og:description": "Plone Classic UI theming from scratch" - "property=og:title": "Plone Classic UI theming from scratch" - "keywords": "Plone, Classic UI, theming, scratch" ---- - -(classic-ui-theming-from-scratch-label)= - -# Classic UI theming from scratch - -```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1645 -``` - -Theming based on a filesystem package without any dependency. - -- Theming for Plone 6 Classic UI -- Theme stored in a filesystem package -- Built from scratch -- No dependencies to Barceloneta -- No Diazo needed - - -(classic-ui-theming-from-scratch-package-label)= - -## Theme package - -- Create a theme package as explained here. -- Remove what you do not need -- Overrides -- Static files - - -(classic-ui-theming-from-scratch-static-files-label)= - -## Static files - -Register directory to keep static files - -File: `src/plonetheme/munich/browser/configure.zcml` -Directory: `src/plonetheme/munich/browser/static` - -```xml - - -``` - - -(classic-ui-theming-from-scratch-theme-label)= - -## Theme - -### Manifest - -- Manifest for your theme -- Keep rules empty to disable Diazo - -```ini -[theme] -title = Munich Theme -description = A modernized Plone 6 theme -preview = preview.png -rules = -prefix = /++theme++plonetheme.munich -doctype = -``` - -(classic-ui-from-scratch-bundle-registration-label)= - -### Bundle registration - -```xml - - - - - ++theme++munich/js/munich.min.js - ++theme++munich/css/munich.min.css - True - False - 2020-12-06 12:00:00 - - - -``` - -### Theme registration - -Register your theme via theme.xml - -```xml - - - munich - true - -``` - -### Compile the bundle - -- Compile SASS to SCSS - -Install all requirements and dependencies from package.json: - -```shell -yarn install -``` - -Build the actual bundle: - -```shell -yarn dist -``` - - -### Theming - -- Make use of Bootstrap [variables](https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss) -- Tweak basic settings like rounded corners, shadows, and so on. -- Set custom fonts -- Define your own stuff -- Import Bootstrap (as basis) - - -#### Minimal backend styling - -When you create a theme from scratch, it is convenient to reuse the Barceloneta theme for: - -- Plone toolbar -- add and edit forms -- control panels - -To do so, follow this guide. - -- Create a new CSS file in your theme, such as the following. - - ```scss - @import "@plone/plonetheme-barceloneta-base/scss/variables.colors.plone"; - @import "@plone/plonetheme-barceloneta-base/scss/variables.colors.dark.plone"; - @import "@plone/plonetheme-barceloneta-base/scss/root_variables"; - @import "bootstrap/scss/bootstrap"; - - @import "@plone/plonetheme-barceloneta-base/scss/toolbar"; - @import "@plone/plonetheme-barceloneta-base/scss/controlpanels"; - @import "@plone/plonetheme-barceloneta-base/scss/forms"; - ``` - - ```{tip} - See all the available [Barceloneta SCSS files](https://github.com/plone/plonetheme.barceloneta/tree/master/scss), and import the ones that you want to use. - ``` - -- Add `@plone/plonetheme-barceloneta-base` as a dependency. - - ```shell - yarn add @plone/plonetheme-barceloneta-base - ``` - -- Add a script in {file}`package.json` to compile the CSS. - - ```json - "css-compile-main": "sass --load-path=node_modules --style expanded --source-map --embed-sources --no-error-css plone.scss:../static/plone.css" - ``` - - ```{tip} - Look at [`plonetheme.barcelonta`'s {file}`package.json`](https://github.com/plone/plonetheme.barceloneta/blob/master/package.json) for a few more scripts that can prefix and minify your CSS and get a bundle for use in production. - ``` - -- Run the compilation. - - ```shell - yarn run css-compile-main - ``` - -- Finally, {ref}`register the bundle `. - -With this guide, you will save yourself quite some work on styling the toolbar, the add and edit forms, and control panels, while keeping the rest of your theming separate. - - -#### Templates - -- Add `z3c.jbot` overrides -- Copy templates to customize -- Add custom views for your story - - -### Available themes - -- [`plonetheme.tokyo`](https://github.com/collective/plonetheme.tokyo/) (mobile first, one column) -- [`plonetheme.munich`](https://github.com/collective/plonetheme.munich/) (minimalistic) diff --git a/docs/classic-ui/theming/index.md b/docs/classic-ui/theming/index.md index 1994efed9..6a7357a7b 100644 --- a/docs/classic-ui/theming/index.md +++ b/docs/classic-ui/theming/index.md @@ -9,19 +9,33 @@ myst: (classic-ui-theming-index-label)= -# Theming of Classic UI +# Theming Classic UI + +This section of the documentation describes how to theme Classic UI. + +Small theme changes—such as the site logo and favicon and minimal CSS changes—can be made by {doc}`changing theme settings through the web `. +Other theming methods should be used for larger customizations or entire website designs. +These other methods include creating an add-on, tweaking the Barceloneta theme, Diazo, and from scratch. ```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1645 +Provide more information about the other methods and why a developer should choose one versus another. +``` + +## How-to guides + +```{toctree} +:maxdepth: 2 + +settings-ttw +create-add-on +color-modes ``` +## Reference + ```{toctree} :maxdepth: 2 -barceloneta -diazo -from-scratch -through-the-web -color-mode -``` \ No newline at end of file +scss-structure +css-custom-properties +``` diff --git a/docs/classic-ui/theming/scss-structure.md b/docs/classic-ui/theming/scss-structure.md new file mode 100644 index 000000000..3fc5ba4fd --- /dev/null +++ b/docs/classic-ui/theming/scss-structure.md @@ -0,0 +1,74 @@ +--- +myst: + html_meta: + "description": "SCSS structure for Classic UI themes for Plone" + "property=og:description": "SCSS structure for Classic UI themes for Plone" + "property=og:title": "SCSS structure for Classic UI themes for Plone" + "keywords": "Plone, Classic UI, theming, add-on" +--- + +(classic-ui-theming-theme-structure-label)= + +# Theme structure + +All the theming relevant files are now located inside `src/plonetheme/themebasedonbarceloneta/theme/`: + +```text +./src/plonetheme/themebasedonbarceloneta/theme/ +├── barceloneta-apple-touch-icon-114x114-precomposed.png +├── barceloneta-apple-touch-icon-144x144-precomposed.png +├── barceloneta-apple-touch-icon-57x57-precomposed.png +├── barceloneta-apple-touch-icon-72x72-precomposed.png +├── barceloneta-apple-touch-icon-precomposed.png +├── barceloneta-apple-touch-icon.png +├── barceloneta-favicon.ico +├── index.html +├── manifest.cfg +├── package.json +├── preview.png +├── rules.xml +├── scss +│ ├── _custom.scss +│ ├── _maps.scss +│ ├── _variables.scss +│ └── theme.scss +├── styles +│ ├── theme.css +│ └── theme.min.css +└── tinymce-templates + ├── README.rst + ├── card-group.html + └── list.html +``` + +`index.html` +: Basic HTML structure for the site layout. + +`manifest.cfg` +: Basic theme configuration for the backend. + +`package.json` +: npm package configuration which defines all requirements for theming with barceloneta. + +`rules.xml` +: Diazo rules which translate the `index.html` and fills it with content from the backend. + +`scss/_custom.scss` +: Custom SCSS rules for your theme. + +`scss/_maps.scss` +: Override Bootstrap mapping variables here. + +`scss/_variables.scss` +: Override Bootstrap and/or Barceloneta variables here. + +`scss/theme.scss` +: Base theme file which follows "Option B" of customizing Bootstrap imports to enable custom variable and map injections. + Note that the order of these imports is mandatory to ensure overriding the defaults. + See https://getbootstrap.com/docs/5.3/customize/sass/#importing. + +`styles/theme.css[.min]` +: Compiled CSS styles. + +`tinymce-templates/*.html` +: HTML snippets for the TinyMCE `template` plugin. diff --git a/docs/classic-ui/theming/settings-ttw.md b/docs/classic-ui/theming/settings-ttw.md new file mode 100644 index 000000000..e485e5172 --- /dev/null +++ b/docs/classic-ui/theming/settings-ttw.md @@ -0,0 +1,62 @@ +--- +myst: + html_meta: + "description": "Change Classic UI theme settings through-the-web (TTW) in Plone 6" + "property=og:description": "Change Classic UI theme settings through-the-web (TTW) in Plone 6" + "property=og:title": "Change Classic UI theme settings through-the-web (TTW) in Plone 6" + "keywords": "Plone 6, Classic UI, Through-the-web, TTW, theme, customization" +--- + +(classic-ui-through-the-web-label)= + +# Change theme settings TTW + +This chapter describes how to change Classic UI theme settings through-the-web ({term}`TTW`) in Plone 6. + +Small theme changes can be made via control panels or by updating Plone 6 Classic UI's `custom.css`. +Other theming methods should be used for larger customizations or entire website designs. + + +(classic-ui-through-the-web-control-panels-label)= + +## Control panels + +You can make the following changes through control panels. + +- Logo +- Favicon +- Custom Styles + + +### Logo + +Navigate to {menuselection}`Admin --> Site Setup --> Site`, or visit the URL path `/@@site-controlpanel` in your web browser's address bar. + +Under {guilabel}`Site Logo`, you can upload a custom logo for your site. + + +### Favicon + +Navigate to {menuselection}`Admin --> Site Setup --> Site`, or visit the URL path `/@@site-controlpanel` in your web browser's address bar. + +Under {guilabel}`Site Favicon`, you can upload a custom favicon for your site. + +When you upload a new favicon, the previous field {guilabel}`MIME type of the site favicon` will update with the favicon's correct media type. + + +### Custom Styles + +Navigate to {menuselection}`Admin --> Site Setup --> Theming --> Advanced settings --> Custom Styles`, or visit the URL path `/@@theming-controlpanel#autotoc-item-autotoc-2` in your web browser's address bar. + +Enter any arbitrary styles, and save your changes. +The changes are stored in the file {file}`custom.css`. +It is shipped as the last resource after all other CSS files. +It can be used to override default CSS, sometimes with the use of the CSS property `!important` or specific CSS selectors. + +However, you should use it only for small changes to CSS. +For larger changes, see {doc}`create-add-on`. + + +## Themes + +Under {menuselection}`Admin --> Site Setup --> Theming --> Themes`, you are limited to downloading and uploading themes. diff --git a/docs/classic-ui/theming/through-the-web.md b/docs/classic-ui/theming/through-the-web.md deleted file mode 100644 index a79b55d62..000000000 --- a/docs/classic-ui/theming/through-the-web.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -myst: - html_meta: - "description": "Through-the-web (TTW) theme customization in Plone 6 Classic UI" - "property=og:description": "Through-the-web (TTW) theme customization in Plone 6 Classic UI" - "property=og:title": "Through-the-web (TTW) theme customization in Plone 6 Classic UI" - "keywords": "Plone 6, Classic UI, Through-the-web, TTW, theme, customization" ---- - -(classic-ui-through-the-web-label)= - -# Through-the-web (TTW) theme customization - -```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1645 -``` - -TTW customization is useful when you need to make small CSS changes. -Theme changes can be made via control panels or by updating Plone 6 Classic UI's `custom.css`. -Other theming methods should be used for larger customizations or entire website designs. - - -(classic-ui-through-the-web-control-panels-label)= - -## Control panels - -You can make the following changes through control panels. - -* Logo -* Favicon -* Custom CSS in `custom.css` - -With `custom.css`, you can make custom styles without compilation. -It is shipped as the last resource after all other CSS files. -It can be used to override default CSS, sometimes with the use of the CSS property `!important` or specific CSS selectors. - - -```{todo} -Provide usage. -Provide navigation through {menuselection}`Site Setup --> Theming` or {guilabel}`Button Name`. -Add screenshots. -``` - - -(classic-ui-through-the-web-css-variables-label)= - -## CSS variables - -Plone uses Bootstrap's CSS variables. -They are used to tweak colors, fonts, spacing, and other CSS attributes. - -```{todo} -Provide usage. -``` - - -(classic-ui-through-the-web-theming-control-panel-label)= - -## Theming control panel - -The Theming control panel is limited to downloading and uploading themes. - - -(classic-ui-through-the-web-templates-label)= - -### Templates - - -(classic-ui-through-the-web-restricted-python-label)= - -### Restricted python - - -(classic-ui-through-the-web-content-types-label)= - -### Content types - From 617c9920260c1a3f40a02f393377f68e266cbc15 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Jan 2025 00:03:25 -0800 Subject: [PATCH 2/3] Update docs/classic-ui/theming/settings-ttw.md Co-authored-by: Peter Mathis --- docs/classic-ui/theming/settings-ttw.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/settings-ttw.md b/docs/classic-ui/theming/settings-ttw.md index e485e5172..4c83d30c5 100644 --- a/docs/classic-ui/theming/settings-ttw.md +++ b/docs/classic-ui/theming/settings-ttw.md @@ -13,7 +13,7 @@ myst: This chapter describes how to change Classic UI theme settings through-the-web ({term}`TTW`) in Plone 6. -Small theme changes can be made via control panels or by updating Plone 6 Classic UI's `custom.css`. +Small theme changes can be made via control panels. Other theming methods should be used for larger customizations or entire website designs. From 08cda10a73700ea6949f091d68f94e8e9d03dc18 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Jan 2025 00:20:09 -0800 Subject: [PATCH 3/3] Update settings-ttw.md --- docs/classic-ui/theming/settings-ttw.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/settings-ttw.md b/docs/classic-ui/theming/settings-ttw.md index 4c83d30c5..75fb6b7a2 100644 --- a/docs/classic-ui/theming/settings-ttw.md +++ b/docs/classic-ui/theming/settings-ttw.md @@ -49,7 +49,7 @@ When you upload a new favicon, the previous field {guilabel}`MIME type of the si Navigate to {menuselection}`Admin --> Site Setup --> Theming --> Advanced settings --> Custom Styles`, or visit the URL path `/@@theming-controlpanel#autotoc-item-autotoc-2` in your web browser's address bar. Enter any arbitrary styles, and save your changes. -The changes are stored in the file {file}`custom.css`. +The changes are stored in a `BrowserView` called `custom.css`. It is shipped as the last resource after all other CSS files. It can be used to override default CSS, sometimes with the use of the CSS property `!important` or specific CSS selectors.