Documentation for updating a Barceloneta theme in Plone 6 classic

Plone Support Theming
1

The docs Classic UI theming based on Barceloneta – Classic UI – Theming of Classic UI — Plone Documentation v6.0 and the training docs 3. Create a theme based on Barceloneta – Plone 6 Classic UI Theming — Plone Training 2023 documentation both suggest using plonecli to create the theme, plonecli add theme_barceloneta which creates all of the boilerplate needed. Importantly for this post, it creates theme/scss/theme.scss as a starting point.

Let's say I created that theme with @plone/plonetheme-barceloneta-base 3.0.0 and want to upgrade to the latest. It's not enough to just update my package.json and reinstall, because there are changes that need to be made to theme/scss/theme.scss. For instance I need to add the line @import "bootstrap/scss/variables-dark"; because of changes in bootstrap. It seems like I could either look at the template directly https://github.com/plone/bobtemplates.plone/blob/main/bobtemplates/plone/theme_barceloneta/src/%2Bpackage.namespace%2B/%2Bpackage.name%2B/theme/scss/theme.scss if I know where to find it, or build a new theme with plonecli and cherry pick out the parts I want to use (the updated theme/scss/theme.scss, or at least parts of it).

Personal take in this paragraph: the process seems a little awkward because it relies on bobtemplates. If you wanted to upgrade to a version of plonetheme.barceloneta that was not the latest, I don't know how you'd cross reference your version of plonetheme.barceloneta with the version of bobtemplates.plone you need. My instinct is that if I'm trying to upgrade plonetheme.barceloneta the tools and documentation I need for doing that should come from that package, pinned to a particular version in VCS. I think using bobtemplates simplifies the initial setup (perhaps) but makes upgrading much more confusing. If plonetheme.barceloneta just came with a template theme.scss and instruction to use that as the basis of my new theme, then I could just grab that from the version I want to use.

Personal preferences aside, I think at the least classic docs should add a section on how to update. Am I correct that they should say to update your package.json, reinstall, and then update the theme.scss by referencing the latest in the bobtemplate?

2

Thank's for pointing that out. We've been discussing that already here Fix SCSS imports for Bootstrap 5.3 by petschki · Pull Request #550 · plone/bobtemplates.plone · GitHub but you're right, that this needs to be documented in the docs.

Classic-UI docs needs some love in general so its always good to check the issues and PRs in the plone/mockup and plonetheme.barceloneta repositories for hints.

3

the problem is here:

While bobtemplates does not import whole bootstrap in one step, barceloneta does. Bobtemplates create a theme based on styles of barceloneta, NOT a customization of barceloneta.

What you want is to tag bobtemplates to barceloneta versions but this is not possible. There's also a problem here:

because bobtemplates does not pin to a specific version of bootstrap (or major version 5.2, 5.3).

This is not a Plone problem, it is theme development. If you want to change bootstrap version, it is up to you to fix differences looking at the history of bobtemplates.

If you, instead, created a theme starting from plonetheme-barceloneta-base 3.0.0 and then add some customization, the history of plonetheme-barceloneta-base will tell you what has changed.