Víctor Fernández de Alba: Plone 5 theming

published Oct 15, 2015

Talk by Víctor Fernández de Alba at the Plone Conference 2015 in Bucharest.

Barceloneta is a neighbourhood in Barcelona. It is also the default diazo theme in Plone 5.

Every resource has its own purpose, like scaffolding, normalizing. We have variables.plone.less that defines all the variables that we use in the theme. You can change them in the Plone UI, or on the file system.

It is based on bootstrap 3, but is not dependent on it. We took a 'photo' of bootstrap at some point, and went from there. We prepended plone- whenever possible. Oriol Marti and Albert Casado Celma helped a lot creating the Barceloneta theme. The original bootstrap resources are included on Plone.

We preserved Plone legacy classes and ids, to try not to break old themes. Things like: .portlet, .formControls are still there.

We updated breadcrumbs, images, portlets, alerts, control panels, buttons, almost everything.

New viewlet manager: plone.mainnavigation, with the folder sections in it.

We used http://fontello.com to build a customized set of icons. Used in plone bundle and Barceloneta. See Products.CMFPlone/static/fonts. Just load config.json in Fontello and start adding your own icons.

Plone Toolbar. See plone.app.layout and plone.app.contentmenu. Small changes since last year. You can change the orientation in the site control panel, so make it horizontal at the top. Do not forget to make space for the toolbar in your Diazo theme.

For the control panel we also used a Fontello font. Add a CSS class with the normalized name of your new control panel item, something like:

icon-controlpanel-FilterSettings: before {content: \e844}

Easy backend customization, by reusing Barceloneta resources. You can use the backend.xml Diazo rules and related css. In the future you can use the Plone Intranet theme switcher.

We use the new Resource Registries introduced in Plone 5. A resource is a collection of less files and javascript. So it is more like a web component for Plone.

Then you can register a bundle: a collection of resources.

You can do easy customization of ++plone++ resources. Why only allow exactly those resources and not others? I think it can be very useful.

Automatic variables:

@import url("@{mockup-patterns-select2}");

This is available for every resource, used in compilation.

You should no longer fill the javascript_head_slot or style_slot in a template, but in a view do add_resource_on_request, or add_bundle_on_request. Use this if you are going to use it just in one view.

Console script helpers:


Call them with:

--site-id=myplonesite --bundle=mybundle

A pure Diazo theme is easy for a designer to jump in. Distributed through a zip file for import and export. Diazo bundles preserves this pureness. This uses new attributes for the manifest.cfg file of the theme, like enabled-bundles, tinymce-content-css, production-js.

Some best practices:

  • Probably no best practices that fit every scenario.

  • Reuse Barceloneta as far as you want. There is an optional Barceloneta profile to register its resources. If you want this, then in your metadata.xml add this as dependency:

  • You are not tied to bootstrap, you can use what you want. Bootstrap is probably easier though.

  • Don't be obsessed with the number of requests your site is doing: HTTP 2.0 is almost here, which helps a lot. It is still important, but it will be less so.

  • Skin layers are not allowed. Okay, they are still there, but please don't use them. Use plone.resource instead.

  • For overriding resources: use z3c.jbot.

  • You can use the extend feature:

    .context:extend( .btn-primary) { }
  • Adapt the grid in Diazo if you want, or via a custom transform like Mosaic is doing.

  • Do not create a theme from scratch yourself, but use bobtemplates.plone. Understand the structure of the default theme.

  • TinyMCE: custom generated style sheets. Define the new Diazo Tiny content specific css in manifest.cfg. TinyMCE content templates are now in core.

  • You can define an nginx passthrough for static plone.resources, so ones that are ++something++. Point it to the local file system for that package, probably using collective.recipe.omelette.

Useful tools:

  • Chrome reloader: Eric Brehault's button.
  • ?diazo.off=1 and ?diazo.debug=1 in the url
  • @@test_rendering page with the common rendering items of Plone.

TTW (Through The Web) is back. You can change the logo in the UI now. plone.app.theming has more power than ever before. It can attract new people. It is easy to do things that should be easy, so non technical people can try out Plone fast. And complex things are possible.

You can try out collective.jbot as customization story, not to be confused with z3c.jbot. Should work on Plone 5 soon, please help.

Overriding ++namespace++ would be nice, especially for sites where you have different parts that want to look slightly differently.

If five add-ons add five bundles, this may be much. We may need to find a better way for this. Also, if all those bundles depend op jQuery, you will get five big bundles, plus the default big plone one.