From e08c0792394474df3d6b3299e56537d011a1ee31 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 18 Feb 2025 02:56:10 -0800 Subject: [PATCH 01/25] Update tips submodules/plone.api submodules/volto --- submodules/plone.api | 2 +- submodules/volto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/submodules/plone.api b/submodules/plone.api index c9a35d75c..55625eca0 160000 --- a/submodules/plone.api +++ b/submodules/plone.api @@ -1 +1 @@ -Subproject commit c9a35d75c989fec96ded09ecd91cbf037ee0402d +Subproject commit 55625eca070ffb3555509a7cfb49f61e08a63f1f diff --git a/submodules/volto b/submodules/volto index a060c4c24..8a4cd22f7 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit a060c4c24f6f7afdb3f5bbbded1740744d9db33b +Subproject commit 8a4cd22f74ce324435855326f9efe008419c0841 From 1f0a07b22e7b99ea3f4fb32a68203ad6284bb441 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 18 Feb 2025 05:30:41 -0800 Subject: [PATCH 02/25] Update tip submodules/volto --- submodules/volto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/volto b/submodules/volto index 8a4cd22f7..3b46e82bb 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 8a4cd22f74ce324435855326f9efe008419c0841 +Subproject commit 3b46e82bb9e00af69946f039e77b4ad2c2e1d39e From cc4288e5cfbc8dcfdf54c1701e42250b4c2a5c83 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 18 Feb 2025 05:47:42 -0800 Subject: [PATCH 03/25] Fix broken references (#1868) * Fix broken references - `link.svg` - `_inc/_install-browser-reqs-volto.md` * Fix linkcheck to bobtemplates * Update tip submodules/volto * Fix link --- docs/_inc/_install-browser-reqs-volto.md | 10 ---------- docs/classic-ui/mockup.md | 2 +- docs/install/create-project-cookieplone.md | 5 ++++- docs/install/create-project.md | 2 +- 4 files changed, 6 insertions(+), 13 deletions(-) delete mode 100644 docs/_inc/_install-browser-reqs-volto.md diff --git a/docs/_inc/_install-browser-reqs-volto.md b/docs/_inc/_install-browser-reqs-volto.md deleted file mode 100644 index b5db8d42a..000000000 --- a/docs/_inc/_install-browser-reqs-volto.md +++ /dev/null @@ -1,10 +0,0 @@ -You can view the list of supported browsers for Volto at [Browserslist](https://browsersl.ist/#q=%3E1%25%0Alast+4+versions%0AFirefox+ESR%0Anot+dead). - -These browsers are set according to the `browserslist` key in Volto's [`package.json`](https://github.com/plone/volto/blob/1aff8d0451f5cb375ca9f5afe9b2b72a0555afd8/packages/volto/package.json#L170-L176) file, whose content is below. - -```shell ->1% -last 4 versions -Firefox ESR -not dead -``` diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md index 1ec463f1a..d117eeb0f 100644 --- a/docs/classic-ui/mockup.md +++ b/docs/classic-ui/mockup.md @@ -137,7 +137,7 @@ Alternatively you can implement it in your own templates by adding the CSS class ## References -- [`bobtemplates.plone` documentation](https://bobtemplatesplone.readthedocs.io/en/latest/) +- [`bobtemplates.plone` documentation](https://bobtemplatesplone.readthedocs.io/) - [`mr.bob` documentation](https://mrbob.readthedocs.io/en/latest/) - [Plone CLI documentation](https://plonecli.readthedocs.io/en/latest/) - [`bobtemplates.plone` repository](https://github.com/plone/bobtemplates.plone) diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 5ba9ec64c..5429f8fb1 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -35,7 +35,10 @@ Plone 6 has both hardware requirements and software prerequisites. ### Supported web browsers -```{include} /_inc/_install-browser-reqs-volto.md +```{include} /volto/_inc/_install-browser-reqs-volto.md +``` + +```{include} /_inc/_install-browser-reqs-classic-ui.md ``` diff --git a/docs/install/create-project.md b/docs/install/create-project.md index 0d8598bbe..13d354987 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -32,7 +32,7 @@ Plone 6.0 has both hardware requirements and software prerequisites. ### Supported web browsers -```{include} /_inc/_install-browser-reqs-volto.md +```{include} /volto/_inc/_install-browser-reqs-volto.md ``` ```{include} /_inc/_install-browser-reqs-classic-ui.md From 4dd1406f103e8402e8f6ac3ace36e75e5c5c4a4a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 18 Feb 2025 05:48:33 -0800 Subject: [PATCH 04/25] Update tip submodules/plone.api --- submodules/plone.api | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/plone.api b/submodules/plone.api index 55625eca0..a876d7064 160000 --- a/submodules/plone.api +++ b/submodules/plone.api @@ -1 +1 @@ -Subproject commit 55625eca070ffb3555509a7cfb49f61e08a63f1f +Subproject commit a876d70649458e6eecb6786156cc53eae4add5e9 From 710db4f15276a058eda7c7faecbb2fd662f2b56e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 19 Feb 2025 02:02:27 -0800 Subject: [PATCH 05/25] Update tip submodules/volto --- submodules/volto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/volto b/submodules/volto index 3b46e82bb..a121c2b54 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 3b46e82bb9e00af69946f039e77b4ad2c2e1d39e +Subproject commit a121c2b5451d407cbfe8c681b3657fc5edbc3136 From 7e0abedb803c43e9aab54de8482c6a450aa4f1af Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Thu, 20 Feb 2025 11:32:22 +0100 Subject: [PATCH 06/25] initial structure of Theming with Diazo --- docs/classic-ui/theming/diazo.md | 121 +++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/classic-ui/theming/diazo.md diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md new file mode 100644 index 000000000..a5ef48a8e --- /dev/null +++ b/docs/classic-ui/theming/diazo.md @@ -0,0 +1,121 @@ +--- +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 +``` + +Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. With Diazo, you can take an HTML wireframe created by a web designer and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. + +When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. And by allowing you seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex requirements possible. + +## Create an addon package + +To create a Diazo theme, you need to create an add.on package. To do so, you can do it using `plonecli`. + +``` +plonecli create addon diazo.theme +``` + +You need to answer to all the questions, you can accept the default ones. + +Then you need to add a `theme` to the add-on package, you can do it like this using `plonecli`: + +``` +cd diazo.theme +plonecli add theme +``` + +you need to answer the question of the theme name and you are done! + +## Theme structure + +This process has created a `theme` folder inside diazo.theme/src/diazo/theme, with the following structure: + +``` +$ tree . +. +├── index.html +├── manifest.cfg +├── package.json +├── README.rst +├── rules.xml +├── styles +│   ├── theme.min.css +│   └── theme.scss +└── tinymce-templates + ├── bs-dark-hero.html + ├── bs-hero-left.html + └── bs-pricing.html + +3 directories, 10 files +``` + +## How to integrate an external theme using Diazo + +First of all you need to have a theme built externally to Plone. It should be composed by the required HTML, CSS and JS files. + +CSS and JS files should be properly versioned or hashed, in order to avoid any caching problems whenever the theme is updated. + +If the CSS file is called `global.css` and your designer updates the CSS without changing the file name, you will surely face caching issues because browsers, varnish or other proxy servers *may* cache your files and may not serve them fresh to the end users. + +To avoid so, it is common to use CSS bundling techniques using npm tooling like Gulp, Grunt or Webpack, and create hashed or versioned filenames for CSS and JS files like + +``` + + + + +``` + +When you have all files of your theme, put them in the `theme` folder, and organize the CSS and JS folders like you have received from your designer. + +You may want to remove the plonecli generated `styles` and `tinymce-templates` folders. + +## Adjust the theme manifest + +Open the `manifest.cfg` file. You will see the following lines there: + +``` +production-css = ++theme++my-shiny-theme/styles/theme.min.css +tinymce-content-css = ++theme++my-shiny-theme/styles/theme.min.css +``` + +Comment them, and leave them like this: + +``` +# production-css = ++theme++my-shiny-theme/styles/theme.min.css +# tinymce-content-css = ++theme++my-shiny-theme/styles/theme.min.css +``` + +This way we signal that we don't want either Plone or Diazo manage the CSS files at all. + +But it means that we will need to handle them in our design HTML files. + +## HTML Template structure + +You want to have an as simple as possible theme because that means that your `rules.xml` file will also be simple. + +The `rules.xml` file is the file that will say which parts of theme will be repaced by the HTML produced by Plone. + +It is a good practice to have a div called `content` in your theme which will contain the maximum space of the content area of your site, because that way you can inject the HTML produced by Plone there using Plone's content section too. + +So, you will be adding a stanza like this in your `rules.xml` file: + + +``` + +``` + + From 676f20464398b6e95f8e793eebf8aeb4585e76ef Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Thu, 20 Feb 2025 11:58:49 +0100 Subject: [PATCH 07/25] more doc --- docs/classic-ui/theming/diazo.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index a5ef48a8e..a290dd23e 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -118,4 +118,13 @@ So, you will be adding a stanza like this in your `rules.xml` file: ``` +## How to theme using diazo + +You can start with the provided `rules.xml` file and you will need to write your own rules to bring the dynamic content from Plone to the theme. + +Sometimes you will face difficult situations where you may find hard to put in the same place items that Plone produces in very different places. + +For instance, you may need to put together the main menu, the language change and the search box. Sometimes it is easier just to override the corresponding template in Plone, build the new html structure there and just replace one thing in the `rules.xml` file than trying to write complex diazo rules (even writing XSLT sometimes). + +The size of the rules.xml file and the number of rules there can impact in the performance of your site. From 48922093778b0540239942a00134cd165989e939 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Thu, 20 Feb 2025 11:32:22 +0100 Subject: [PATCH 08/25] initial structure of Theming with Diazo --- docs/classic-ui/theming/diazo.md | 121 +++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/classic-ui/theming/diazo.md diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md new file mode 100644 index 000000000..a5ef48a8e --- /dev/null +++ b/docs/classic-ui/theming/diazo.md @@ -0,0 +1,121 @@ +--- +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 +``` + +Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. With Diazo, you can take an HTML wireframe created by a web designer and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. + +When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. And by allowing you seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex requirements possible. + +## Create an addon package + +To create a Diazo theme, you need to create an add.on package. To do so, you can do it using `plonecli`. + +``` +plonecli create addon diazo.theme +``` + +You need to answer to all the questions, you can accept the default ones. + +Then you need to add a `theme` to the add-on package, you can do it like this using `plonecli`: + +``` +cd diazo.theme +plonecli add theme +``` + +you need to answer the question of the theme name and you are done! + +## Theme structure + +This process has created a `theme` folder inside diazo.theme/src/diazo/theme, with the following structure: + +``` +$ tree . +. +├── index.html +├── manifest.cfg +├── package.json +├── README.rst +├── rules.xml +├── styles +│   ├── theme.min.css +│   └── theme.scss +└── tinymce-templates + ├── bs-dark-hero.html + ├── bs-hero-left.html + └── bs-pricing.html + +3 directories, 10 files +``` + +## How to integrate an external theme using Diazo + +First of all you need to have a theme built externally to Plone. It should be composed by the required HTML, CSS and JS files. + +CSS and JS files should be properly versioned or hashed, in order to avoid any caching problems whenever the theme is updated. + +If the CSS file is called `global.css` and your designer updates the CSS without changing the file name, you will surely face caching issues because browsers, varnish or other proxy servers *may* cache your files and may not serve them fresh to the end users. + +To avoid so, it is common to use CSS bundling techniques using npm tooling like Gulp, Grunt or Webpack, and create hashed or versioned filenames for CSS and JS files like + +``` + + + + +``` + +When you have all files of your theme, put them in the `theme` folder, and organize the CSS and JS folders like you have received from your designer. + +You may want to remove the plonecli generated `styles` and `tinymce-templates` folders. + +## Adjust the theme manifest + +Open the `manifest.cfg` file. You will see the following lines there: + +``` +production-css = ++theme++my-shiny-theme/styles/theme.min.css +tinymce-content-css = ++theme++my-shiny-theme/styles/theme.min.css +``` + +Comment them, and leave them like this: + +``` +# production-css = ++theme++my-shiny-theme/styles/theme.min.css +# tinymce-content-css = ++theme++my-shiny-theme/styles/theme.min.css +``` + +This way we signal that we don't want either Plone or Diazo manage the CSS files at all. + +But it means that we will need to handle them in our design HTML files. + +## HTML Template structure + +You want to have an as simple as possible theme because that means that your `rules.xml` file will also be simple. + +The `rules.xml` file is the file that will say which parts of theme will be repaced by the HTML produced by Plone. + +It is a good practice to have a div called `content` in your theme which will contain the maximum space of the content area of your site, because that way you can inject the HTML produced by Plone there using Plone's content section too. + +So, you will be adding a stanza like this in your `rules.xml` file: + + +``` + +``` + + From df3470410e0fff780a23953943474bdd82670426 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Thu, 20 Feb 2025 11:58:49 +0100 Subject: [PATCH 09/25] more doc --- docs/classic-ui/theming/diazo.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index a5ef48a8e..a290dd23e 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -118,4 +118,13 @@ So, you will be adding a stanza like this in your `rules.xml` file: ``` +## How to theme using diazo + +You can start with the provided `rules.xml` file and you will need to write your own rules to bring the dynamic content from Plone to the theme. + +Sometimes you will face difficult situations where you may find hard to put in the same place items that Plone produces in very different places. + +For instance, you may need to put together the main menu, the language change and the search box. Sometimes it is easier just to override the corresponding template in Plone, build the new html structure there and just replace one thing in the `rules.xml` file than trying to write complex diazo rules (even writing XSLT sometimes). + +The size of the rules.xml file and the number of rules there can impact in the performance of your site. From 87b49813b8eda81ae25db8b1c8d9a85a0e4ed607 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 03:59:17 -0800 Subject: [PATCH 10/25] - Add diazo to toctree - Add note update getting help for choosing a theming method --- docs/classic-ui/theming/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/classic-ui/theming/index.md b/docs/classic-ui/theming/index.md index 6a7357a7b..3c188b669 100644 --- a/docs/classic-ui/theming/index.md +++ b/docs/classic-ui/theming/index.md @@ -17,8 +17,8 @@ Small theme changes—such as the site logo and favicon and minimal CSS changes 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} -Provide more information about the other methods and why a developer should choose one versus another. +```{note} +For guidance to choose an appropriate theming method for your use case, you can post to the [Plone Community Forum Classic UI category](https://community.plone.org/c/development/classic-ui/56), or join the [Classic UI channel on Discord](https://discord.com/channels/786421998426521600/787254601656827924). ``` ## How-to guides @@ -29,6 +29,7 @@ Provide more information about the other methods and why a developer should choo settings-ttw create-add-on color-modes +diazo ``` ## Reference From a08782eb90b5821d7a50d76ccdfa4e77a86b6978 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 04:22:24 -0800 Subject: [PATCH 11/25] Clean up grammar, one sentence per line, MyST syntax --- docs/classic-ui/theming/diazo.md | 104 ++++++++++++++++--------------- 1 file changed, 55 insertions(+), 49 deletions(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index a290dd23e..3c0c50b44 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -11,40 +11,38 @@ myst: # 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 -``` +Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. +With Diazo, you can take an HTML wireframe created by a web designer, and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. -Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. With Diazo, you can take an HTML wireframe created by a web designer and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. +When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. +And by allowing you to seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex requirements possible. -When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. And by allowing you seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex requirements possible. -## Create an addon package +## Create an add-on package -To create a Diazo theme, you need to create an add.on package. To do so, you can do it using `plonecli`. +To create a Diazo theme, you need to create an add-on package with [`plonecli`](https://github.com/plone/plonecli). -``` +```shell plonecli create addon diazo.theme ``` -You need to answer to all the questions, you can accept the default ones. +Answer all the questions. -Then you need to add a `theme` to the add-on package, you can do it like this using `plonecli`: +Next, add a theme called "theme" to the add-on package using `plonecli`. ``` cd diazo.theme plonecli add theme ``` -you need to answer the question of the theme name and you are done! +Answer the question of the theme name. -## Theme structure -This process has created a `theme` folder inside diazo.theme/src/diazo/theme, with the following structure: +### Theme structure -``` -$ tree . +This process creates a {file}`theme` folder inside {file}`diazo.theme/src/diazo/theme`, with the following structure. + +```console . ├── index.html ├── manifest.cfg @@ -52,79 +50,87 @@ $ tree . ├── README.rst ├── rules.xml ├── styles -│   ├── theme.min.css -│   └── theme.scss +│ ├── theme.min.css +│ └── theme.scss └── tinymce-templates ├── bs-dark-hero.html ├── bs-hero-left.html └── bs-pricing.html - -3 directories, 10 files ``` -## How to integrate an external theme using Diazo -First of all you need to have a theme built externally to Plone. It should be composed by the required HTML, CSS and JS files. +## Integrate an external theme using Diazo -CSS and JS files should be properly versioned or hashed, in order to avoid any caching problems whenever the theme is updated. +Begin with any theme from outside Plone. +It should be composed of the required HTML, CSS, and JavaScript files. -If the CSS file is called `global.css` and your designer updates the CSS without changing the file name, you will surely face caching issues because browsers, varnish or other proxy servers *may* cache your files and may not serve them fresh to the end users. +CSS and JavaScript files should be properly versioned or hashed to avoid any caching problems whenever the theme is updated. -To avoid so, it is common to use CSS bundling techniques using npm tooling like Gulp, Grunt or Webpack, and create hashed or versioned filenames for CSS and JS files like +If the CSS file is called {file}`global.css`, and your designer updates the CSS without changing the file name, you will surely face caching issues. +Browsers, varnish, or other proxy servers might cache your files, and not serve them to the end users until the cache expires or gets flushed. -``` - +To avoid this issue, CSS bundling techniques that use npm tooling—such as Gulp, Grunt, or Webpack—create hashed or versioned filenames for CSS and JavaScript files. +The following HTML snippets show examples of versioned files. +```html + - ``` -When you have all files of your theme, put them in the `theme` folder, and organize the CSS and JS folders like you have received from your designer. +When you have all files of your theme, put them in the {file}`theme` folder, and organize the CSS and JavaScript folders as you received them from your designer. + +You may want to remove the `plonecli` generated `styles` and `tinymce-templates` folders. -You may want to remove the plonecli generated `styles` and `tinymce-templates` folders. ## Adjust the theme manifest -Open the `manifest.cfg` file. You will see the following lines there: +Open the {file}`manifest.cfg` file. +You will see the following lines. -``` +```cfg production-css = ++theme++my-shiny-theme/styles/theme.min.css tinymce-content-css = ++theme++my-shiny-theme/styles/theme.min.css ``` -Comment them, and leave them like this: +Comment them out as shown. -``` +```cfg # production-css = ++theme++my-shiny-theme/styles/theme.min.css # tinymce-content-css = ++theme++my-shiny-theme/styles/theme.min.css ``` -This way we signal that we don't want either Plone or Diazo manage the CSS files at all. - -But it means that we will need to handle them in our design HTML files. +This way, you signal that you don't want either Plone or Diazo to manage the CSS files at all. +But it means that you will need to handle them in your design HTML files. -## HTML Template structure -You want to have an as simple as possible theme because that means that your `rules.xml` file will also be simple. +## HTML template structure -The `rules.xml` file is the file that will say which parts of theme will be repaced by the HTML produced by Plone. +Your theme should be as simple as possible. +That will make your {file}`rules.xml` file also as simple as possible. -It is a good practice to have a div called `content` in your theme which will contain the maximum space of the content area of your site, because that way you can inject the HTML produced by Plone there using Plone's content section too. +The {file}`rules.xml` file declares which parts of theme will be replaced by the HTML produced by Plone. -So, you will be adding a stanza like this in your `rules.xml` file: +It is a good practice to have a `
` element called `content` in your theme, which will contain the maximum space of the content area of your site. +That way you can inject the HTML produced by Plone there using Plone's content section too. +Add a stanza in your {file}`rules.xml` file. -``` - +```xml + ``` -## How to theme using diazo -You can start with the provided `rules.xml` file and you will need to write your own rules to bring the dynamic content from Plone to the theme. +## How to theme using Diazo -Sometimes you will face difficult situations where you may find hard to put in the same place items that Plone produces in very different places. +You can start with the provided {file}`rules.xml` file. +You will need to write your own rules to bring the dynamic content from Plone into the theme. -For instance, you may need to put together the main menu, the language change and the search box. Sometimes it is easier just to override the corresponding template in Plone, build the new html structure there and just replace one thing in the `rules.xml` file than trying to write complex diazo rules (even writing XSLT sometimes). +Sometimes you will face difficult situations where you may find it hard to put items in the same place that Plone produces in very different places. -The size of the rules.xml file and the number of rules there can impact in the performance of your site. +For instance, you may need to put together the main menu, the language change, and the search box. +Sometimes it is easier to override the corresponding template in Plone, build the new HTML structure there, and replace one thing in the {file}`rules.xml` file than trying to write complex Diazo rules or writing XSLT. +The size of the {file}`rules.xml` file and the number of rules it contains can negatively impact the performance of your site. From cc749b34f3a2ffbfd2b8d383eafd354670cd001d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 04:24:06 -0800 Subject: [PATCH 12/25] Add language --- docs/classic-ui/theming/diazo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 3c0c50b44..878f79b70 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -30,7 +30,7 @@ Answer all the questions. Next, add a theme called "theme" to the add-on package using `plonecli`. -``` +```shell cd diazo.theme plonecli add theme ``` From 03412812e7cecceb027c26902b9c81487cf2c234 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 04:37:50 -0800 Subject: [PATCH 13/25] Move concepts and advice into a new Theme development advice section --- docs/classic-ui/theming/diazo.md | 40 +++++++++++++++++++------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 878f79b70..3fe7b637e 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -64,25 +64,12 @@ This process creates a {file}`theme` folder inside {file}`diazo.theme/src/diazo/ Begin with any theme from outside Plone. It should be composed of the required HTML, CSS, and JavaScript files. -CSS and JavaScript files should be properly versioned or hashed to avoid any caching problems whenever the theme is updated. - -If the CSS file is called {file}`global.css`, and your designer updates the CSS without changing the file name, you will surely face caching issues. -Browsers, varnish, or other proxy servers might cache your files, and not serve them to the end users until the cache expires or gets flushed. - -To avoid this issue, CSS bundling techniques that use npm tooling—such as Gulp, Grunt, or Webpack—create hashed or versioned filenames for CSS and JavaScript files. -The following HTML snippets show examples of versioned files. - -```html - - -``` - When you have all files of your theme, put them in the {file}`theme` folder, and organize the CSS and JavaScript folders as you received them from your designer. You may want to remove the `plonecli` generated `styles` and `tinymce-templates` folders. -## Adjust the theme manifest +### Adjust the theme manifest Open the {file}`manifest.cfg` file. You will see the following lines. @@ -103,7 +90,28 @@ This way, you signal that you don't want either Plone or Diazo to manage the CSS But it means that you will need to handle them in your design HTML files. -## HTML template structure +## Theme development advice + +This section describes common practices when developing a Diazo theme. + + +### Avoid cache issues + +CSS and JavaScript files should be properly versioned or hashed to avoid any caching problems whenever the theme is updated. + +If the CSS file is called {file}`global.css`, and your designer updates the CSS without changing the file name, you will surely face caching issues. +Browsers, varnish, or other proxy servers might cache your files, and not serve them to the end users until the cache expires or gets flushed. + +To avoid this issue, CSS bundling techniques that use npm tooling—such as Gulp, Grunt, or Webpack—create hashed or versioned filenames for CSS and JavaScript files. +The following HTML snippets show examples of versioned files. + +```html + + +``` + + +### HTML template structure Your theme should be as simple as possible. That will make your {file}`rules.xml` file also as simple as possible. @@ -123,7 +131,7 @@ Add a stanza in your {file}`rules.xml` file. ``` -## How to theme using Diazo +### How to theme using Diazo You can start with the provided {file}`rules.xml` file. You will need to write your own rules to bring the dynamic content from Plone into the theme. From bccd9ff80206a97bcdad5664d17351a089fa011c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 04:39:06 -0800 Subject: [PATCH 14/25] Minor tweaks --- docs/classic-ui/theming/diazo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 3fe7b637e..42015e1fb 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -119,7 +119,7 @@ That will make your {file}`rules.xml` file also as simple as possible. The {file}`rules.xml` file declares which parts of theme will be replaced by the HTML produced by Plone. It is a good practice to have a `
` element called `content` in your theme, which will contain the maximum space of the content area of your site. -That way you can inject the HTML produced by Plone there using Plone's content section too. +That way you can inject the HTML produced by Plone there using Plone's content section, too. Add a stanza in your {file}`rules.xml` file. From 7960810b949332ed365460d2485fcc041c8d4a64 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 04:41:44 -0800 Subject: [PATCH 15/25] Rename section to reflect its content --- docs/classic-ui/theming/diazo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 42015e1fb..bf4fe6272 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -131,7 +131,7 @@ Add a stanza in your {file}`rules.xml` file. ``` -### How to theme using Diazo +### Minimize rules You can start with the provided {file}`rules.xml` file. You will need to write your own rules to bring the dynamic content from Plone into the theme. From 8cb69c82e0f0eef4f59b8522cedef3816bcde79d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 04:46:04 -0800 Subject: [PATCH 16/25] Adjust heading level --- docs/classic-ui/theming/diazo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index bf4fe6272..5669a1692 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -69,7 +69,7 @@ When you have all files of your theme, put them in the {file}`theme` folder, and You may want to remove the `plonecli` generated `styles` and `tinymce-templates` folders. -### Adjust the theme manifest +## Adjust the theme manifest Open the {file}`manifest.cfg` file. You will see the following lines. From 273daee46830d86a98f92f944f308f7b452e7a93 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 24 Feb 2025 15:24:15 +0100 Subject: [PATCH 17/25] Update diazo.md explain the purpose of each file created when addin a theme --- docs/classic-ui/theming/diazo.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 5669a1692..dd0ae05e4 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -58,6 +58,15 @@ This process creates a {file}`theme` folder inside {file}`diazo.theme/src/diazo/ └── bs-pricing.html ``` +The purpose of each file is the following: + +- `index.html`: this is the theme file. The purpose of Diazo theming is to fill the theme file with the content coming from Plone. +- `manifest.cfg`: this file contains the theme configuration, such as the theme name, the path to the rules file and some other configurations. +- `package.json`: this theme folder is by itself a javascript package, and, in case you want to develop your theme here, in this file you can configure which are the dependencies of your theme. For instance you can add `bootstrap` or `tailwind` as dependencies and manage those dependencies and the building of your final CSS from here. +- `README.rst`: the file that explains how this theme is built and developed. +- `rules.xml`: the file where you will write your rules to bring Plone content to the theme in the `index.html` file +- `styles` folder: where you can save your theme's CSS files. +- `tinymce-templates`: template files that can be loaded into the TinyMCE editor in Plone (it requires additional configuration in the add-ons profile's `registry.xml` file. ## Integrate an external theme using Diazo From 99f70f2ec9ec4de59ae52d54801fc44b73b1f252 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 24 Feb 2025 15:26:28 +0100 Subject: [PATCH 18/25] Update diazo.md Link to Diazo docs. --- docs/classic-ui/theming/diazo.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index dd0ae05e4..79a914dd8 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -143,6 +143,9 @@ Add a stanza in your {file}`rules.xml` file. ### Minimize rules You can start with the provided {file}`rules.xml` file. + +You can read about how to write your rules and their syntax in the [official Diazo documentation](https://docs.diazo.org/en/latest/basic.html) + You will need to write your own rules to bring the dynamic content from Plone into the theme. Sometimes you will face difficult situations where you may find it hard to put items in the same place that Plone produces in very different places. From dee7d8981c477f14f14e71cd0e8a91340cd2a618 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 24 Feb 2025 15:29:38 +0100 Subject: [PATCH 19/25] Update diazo.md --- docs/classic-ui/theming/diazo.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 79a914dd8..b09558dd9 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -22,8 +22,10 @@ And by allowing you to seamlessly integrate XSLT into your rule files, Diazo mak To create a Diazo theme, you need to create an add-on package with [`plonecli`](https://github.com/plone/plonecli). +You can run `plonecli` using [pipx](https://pipx.pypa.io/stable/), without needing to install plonecli, as follows: + ```shell -plonecli create addon diazo.theme +pipx run plonecli create addon diazo.theme ``` Answer all the questions. @@ -32,7 +34,7 @@ Next, add a theme called "theme" to the add-on package using `plonecli`. ```shell cd diazo.theme -plonecli add theme +pipx run plonecli add theme ``` Answer the question of the theme name. From 126fa5d92621df8fe12d8d9d45c22dc0e5bb1990 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 23:10:20 -0800 Subject: [PATCH 20/25] - Make first mention of Diazo a term, already existing in the Glossary - Reuse a sentence from Diazo docs that fills a critical gap in the introduction. - Convert list of files descriptions into a definition list --- docs/classic-ui/theming/diazo.md | 46 +++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index b09558dd9..094e8c5e8 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -11,11 +11,13 @@ myst: # Classic UI theming with Diazo -Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. +{term}`Diazo` allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. With Diazo, you can take an HTML wireframe created by a web designer, and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. +A Diazo theme consists of a static HTML page, referred to as the _theme_, and a rules file, conventionally called {file}`rules.xml`. + When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. -And by allowing you to seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex requirements possible. +And by allowing you to seamlessly integrate XSLT into your rules files, Diazo makes common cases simple, and complex requirements possible. ## Create an add-on package @@ -30,7 +32,7 @@ pipx run plonecli create addon diazo.theme Answer all the questions. -Next, add a theme called "theme" to the add-on package using `plonecli`. +Next, add a theme called `theme` to the add-on package using `plonecli`. ```shell cd diazo.theme @@ -42,7 +44,7 @@ Answer the question of the theme name. ### Theme structure -This process creates a {file}`theme` folder inside {file}`diazo.theme/src/diazo/theme`, with the following structure. +The previous step creates a {file}`theme` folder inside {file}`diazo.theme/src/diazo/theme`, with the following structure. ```console . @@ -60,15 +62,33 @@ This process creates a {file}`theme` folder inside {file}`diazo.theme/src/diazo/ └── bs-pricing.html ``` -The purpose of each file is the following: +The purpose of each item is described as follows. + +{file}`index.html` +: This is the theme file. + Plone populates it with its content, according to rules defined in {file}`rules.xml`. + +{file}`manifest.cfg` +: This file contains the theme configuration, such as the theme name, the path to the rules file and some other configurations. + +{file}`package.json` +: The theme folder is, by itself, a JavaScript package. + If you want to develop your theme here, you can declare the dependencies of your theme in this file. + For instance, you can add `bootstrap` or `tailwind` as dependencies, and manage those dependencies and the building of your final CSS from here. + +{file}`README.rst` +: The file that explains how this theme is built and developed. + +{file}`rules.xml` +: The file where you will write your rules to bring Plone content into the theme in the {file}`index.html` file. + +{file}`styles` folder +: Where you can save your theme's CSS files. + +{file}`tinymce-templates` +: Template files that can be loaded into the TinyMCE editor in Plone. + It requires additional configuration in the add-on's profile's {file}`registry.xml` file. -- `index.html`: this is the theme file. The purpose of Diazo theming is to fill the theme file with the content coming from Plone. -- `manifest.cfg`: this file contains the theme configuration, such as the theme name, the path to the rules file and some other configurations. -- `package.json`: this theme folder is by itself a javascript package, and, in case you want to develop your theme here, in this file you can configure which are the dependencies of your theme. For instance you can add `bootstrap` or `tailwind` as dependencies and manage those dependencies and the building of your final CSS from here. -- `README.rst`: the file that explains how this theme is built and developed. -- `rules.xml`: the file where you will write your rules to bring Plone content to the theme in the `index.html` file -- `styles` folder: where you can save your theme's CSS files. -- `tinymce-templates`: template files that can be loaded into the TinyMCE editor in Plone (it requires additional configuration in the add-ons profile's `registry.xml` file. ## Integrate an external theme using Diazo @@ -146,7 +166,7 @@ Add a stanza in your {file}`rules.xml` file. You can start with the provided {file}`rules.xml` file. -You can read about how to write your rules and their syntax in the [official Diazo documentation](https://docs.diazo.org/en/latest/basic.html) +You can read about how to write your rules and their syntax in the [official Diazo documentation](https://docs.diazo.org/en/latest/basic.html). You will need to write your own rules to bring the dynamic content from Plone into the theme. From d0bc7dd711b37af2d62f5d4ee0251b20a66c3ebe Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Feb 2025 23:17:28 -0800 Subject: [PATCH 21/25] Tweak markup --- docs/classic-ui/theming/diazo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-ui/theming/diazo.md b/docs/classic-ui/theming/diazo.md index 094e8c5e8..b0db9d1de 100644 --- a/docs/classic-ui/theming/diazo.md +++ b/docs/classic-ui/theming/diazo.md @@ -24,7 +24,7 @@ And by allowing you to seamlessly integrate XSLT into your rules files, Diazo ma To create a Diazo theme, you need to create an add-on package with [`plonecli`](https://github.com/plone/plonecli). -You can run `plonecli` using [pipx](https://pipx.pypa.io/stable/), without needing to install plonecli, as follows: +You can run `plonecli` using [pipx](https://pipx.pypa.io/stable/), without needing to install `plonecli`, as follows. ```shell pipx run plonecli create addon diazo.theme From 5e65e3f3a1eebdbba12bb40f158f868468c6d0e6 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Tue, 25 Feb 2025 10:42:21 +0100 Subject: [PATCH 22/25] add tinymce templates docs --- docs/classic-ui/tinymce-customization.md | 32 ++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/classic-ui/tinymce-customization.md b/docs/classic-ui/tinymce-customization.md index 8594ac327..429a82569 100644 --- a/docs/classic-ui/tinymce-customization.md +++ b/docs/classic-ui/tinymce-customization.md @@ -168,3 +168,35 @@ You can also exclude certain URLs from being sandboxed as follows. ```{seealso} See [`sandbox_iframes_exclusions`](https://www.tiny.cloud/docs/tinymce/latest/content-filtering/#sandbox-iframes-exclusions) for TinyMCE's default settings. ``` + + +## Insert preconfigured HTML blocks + +You can add custom HTML blocks in TinyMCE and they can be inserted in your content using the TinyMCE insert template menu option. + +This option is best for system administrators and developers who write their own add-ons to ease reproducibility. + +You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the configuration of the HTML blocks. + +```xml + + + + + Enter the list of templates in json format http://www.tinymce.com/wiki.php/Plugin:template + False + Templates + + [ + {"title": "Image and Text", "url": "++theme++my.theme/tinymce-templates/bs-dark-hero.html"}, + {"title": "Image and Text", "url": "++theme++my.theme/tinymce-templates/bs-hero-left.html"}, + {"title": "Image and Text", "url": "++theme++my.theme/tinymce-templates/bs-pricing.html"}, + ] + + + + +``` + +In this example, we are adding 3 HTML files that contain the a custom HTML. + From fd97ddf450b77eb8dd88ba6d456c7ceb6a9ae444 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 25 Feb 2025 03:39:17 -0800 Subject: [PATCH 23/25] Tidy up --- docs/classic-ui/tinymce-customization.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/classic-ui/tinymce-customization.md b/docs/classic-ui/tinymce-customization.md index 429a82569..9adcbf496 100644 --- a/docs/classic-ui/tinymce-customization.md +++ b/docs/classic-ui/tinymce-customization.md @@ -172,11 +172,13 @@ See [`sandbox_iframes_exclusions`](https://www.tiny.cloud/docs/tinymce/latest/co ## Insert preconfigured HTML blocks -You can add custom HTML blocks in TinyMCE and they can be inserted in your content using the TinyMCE insert template menu option. +You can add custom HTML blocks in TinyMCE. +You can insert them in your content using the TinyMCE insert template menu option. This option is best for system administrators and developers who write their own add-ons to ease reproducibility. You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the configuration of the HTML blocks. +The following example adds three HTML files, each of which contains its custom HTML block. ```xml @@ -194,9 +196,5 @@ You can add a GenericSetup configuration file to your add-on, such as {file}`pro ] - ``` - -In this example, we are adding 3 HTML files that contain the a custom HTML. - From a0779be573c6c0418fdda273f85478887a8a62fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 25 Feb 2025 04:02:55 -0800 Subject: [PATCH 24/25] Add a label and important admonition about Template plugin removal in TinyMCE 7.0 --- docs/classic-ui/tinymce-customization.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/classic-ui/tinymce-customization.md b/docs/classic-ui/tinymce-customization.md index 9adcbf496..194b86faa 100644 --- a/docs/classic-ui/tinymce-customization.md +++ b/docs/classic-ui/tinymce-customization.md @@ -140,7 +140,6 @@ You can remove these formats through the TinyMCE control panel. Once removed, the custom formats will no longer appear in the menu. - ## Configure `