PLIP: Adding Gloss Support to Plone Core

[pigeonflight]

Proposer : David Bain

Seconder : Eric Brehault

Abstract

Plone 5 now ships with Diazo and the Barceloneta Diazo theme out of the box. Gloss is currently an add-on theme that can act as a base theme, it's major feature is that it ships with a special Diazo rule set. Gloss makes it possible for a user to implement new themes without needing to write their own Diazo rules. This PLIP proposes that Gloss be integrated into the Plone core by adding the gloss.xml ruleset file directly to Barceloneta.

The diagram below captures the big idea. Assignment is achieved in the source theme using special gl- css classes such as gl-logo and gl-content.

Motivation

Diazo is fantastic and it has helped to lower the bar for theming Plone sites. Unfortunately there is only a small overlap between those who are fluent with Diazo and those who are empathetic designers. Gloss will make it possible for talented designers to port their themes to Plone without needing to dive deeply into Diazo.

Proposal & Implementation

Gloss builds on Diazo and aims to lower the bar further by providing designers with a handful of reserved css classes (gl- classes) (see: http://the-gloss-project.readthedocs.org/en/master/reference.html).

Implementation

A working version of Gloss already exists, more information is at http://the-gloss-project.readthedocs.org/. Gloss builds on Diazo by providing a set of rules which associate with special (gl- classes).

For example the rule below makes it possible for a designer to add the personal tools menu bar simply by adding the 'gl-user-menu' class to any element in their theme:

 <before css:theme-children=".gl-user-menu"
   css:content="#portal-personaltools-wrapper" />

For a list of currently implemented gl- classes see: http://the-gloss-project.readthedocs.org/en/master/reference.html.

In addition to adding the gloss.xml file I recommend that it be tested with a reference "Gloss powered" theme. This reference theme can also be used in the context of the Plone documentation to help persons get an understanding of how Gloss works.

Deliverables

• An enhanced version of Gloss compatible with bootstrap 3 based themes
• A reference theme (not necessarily in the core)
• Documentation on using Gloss added as a chapter to the Plone Theming documentation

  Risks

Currently Gloss attempts to add support for what I call 'components', e.g. drop down menus and sliders (see: http://the-gloss-project.readthedocs.org/en/master/components.html). These implementations currently target specific add-ons for example if a site has Plone Carousel installed, a designer might be able to 'decorate' a slider in their theme with a few special gl- classes and, based on rules defined in Gloss, dynamically pull in images from the carousel into the theme's slider. Unfortunately at the moment this depends on third-party packages like webcouturier.dropdownmenu and the carousel add-ons. As an example, when Plone moved to Plone 5 and webcouturier.dropdownmenu did not it broke gl- support for dropdown menus.

Possible mitigation

To mitigate against this risk we could target bootstrap behaviour rather than specific add-ons, then if an add-on chooses to implements that behaviour it will inherit the enhancements provided by Gloss. Also we could choose to only ship a version of Gloss that does not work with extra components which we can call "gloss.core". All additional support might be provided with "gloss.extensions".

Participants

David Bain

[ebrehault]

That's a very good idea, I love it.

One thing: you say Gloss "extends" Barceloneta, but it does not, it just contains a copy of Barceloneta, which is obviously a problem (we do not want to maintain the same thing in 2 different modules). So I think it would be better if Gloss was not an additional theme, but directly a new part of Barceloneta: it could be provided as a rule file, and if a user adds: <xi:include href="++theme++barceloneta/gloss.xml" /> to his custom theme, then it enables Gloss. Do you think there is any technical issue with this approach?

[pigeonflight]

@ebrehault I'll update the PLIP to be more accurate regarding how Gloss works. Regarding your question, there's no technical issue that I know of with including a gloss.xml file as part of Barceloneta. BTW... does that make you a seconder on this PLIP?

[ebrehault]

@pigeonflight sure, add me as seconder :)

[pigeonflight]

Added you.

[pigeonflight]

@ebrehault I had the impression that there was an aversion to adding more things directly to Barceloneta, but if the framework team is fine with it, I'll update the PLIP.

[ebrehault]

That is just my opinion, and it will be discussed by the framework team. Maybe you should just mention the 2 possibilities.

[pigeonflight]

I've updated the PLIP to cover the two possibilities. I can definitely see the advantage of shipping Barceloneta with a gloss.xml file.

[jensens]

I'am not a frontend developer, but I really like the whole Gloss idea. Important to me is a perfect documentation at docs.plone.org and that it supports a wide variety of use-cases.

I think we must not include features that are bound to a specific addon. Moreover we should provide generic classes for common UI patterns. I dont know how to do this, but I'am sure it is possible.

[thet]

"diazo by convention"

Gloss is a really nice name and has a really nice logo!

I'm a bit concerned to introduce a new marketing term - this is what big tech companies do with pleasure while they add just more complexity (Microsoft is - or was - a good example for this).

BUT: as I said above, the name and the logo are so nice, that they outweigh my concerns.

[jensens]

@pigeonflight fyi, at todays framework team meeting we we're overall positive to integrate Gloss into Plone, but were not at one how to do this.

At first we see all "Gloss - the rules file" plus its documentation as the major advantage. We overall did not consider to add the whole theme. The gloss.theme - or themes - can still live in its own repository. IIUC the theme is exchangeable and not integral part of gloss. There may be several themes independent from each other (correct me if I am wrong anywhere).

Would that a reasonable approach?

The second discussion was about the place the rules shall live. Some proposed to make it -pragmatic approach - part of Barcelonetta (like backend.xml), others want it - more the academic approach from a separation-of-concerns POV - to live separate in plone.app.theming or Products.CMFPlone.

What do you think?

[djay]

I worry that if it's not part of barcelonetta then it will get missed by new developers (whose first impulse will be to want to customise the out of the box theme), and also it will be less maintained in the core (like the bootstrap example used to be). The only downside I can think of is backwards incompatibility. This could be mitigated by getting it in sooner before too many build their themes on top of barceloneta.

[pigeonflight]

I'm excited that the Gloss concept is resonating with the framework team and give that I use it, I'm extremely biased towards it :). In terms of where to put it, I think shipping it with the barceloneta theme would make it both easier to explain and maintain, I think that would be a big win.

@jensens I'm not tied to the whole theme, the extra rules could easily ship with the full gloss.theme as you suggest.

[jensens]

@pigeonflight great! Next step: Please edit your proposal above, so this option is targeted. Also the documentation of the gloss core usage at least needs to become part of the plone theming documentation, as an own chapter I'd say? Please add all this and everything I forgot about also to the proposal.

[pigeonflight]

I've done the updates. What is left to complete this PLIP?

[ebrehault]

@pigeonflight oh sorry, I didn't noticed the changes early enough (Github only notifies on comments, but not on issue body text changes, that's a shame). We will discuss this PLIP during next FWT meeting.

[pbauer]

The xml-file in question that would be included is here: https://github.com/GlossProject/gloss.theme/blob/master/gloss/theme/diazo_resources/gloss.xml

[thet]

I like the idea of Gloss! But I'm not sure if I want to see it in core but better as "recommended" add on. I'm still concerned about the proposal where to add the gloss.xml file. Just into plonetheme.barceloneta because we don't know of a better place? I feel that's wrong and it will orphaned there. Gloss provides a separate independent functionality and would be perfect in it's own package. I'm OK with adding it as a separate package to Plone core. Of course, we want to reduce the number of packages - but the main problem with Plone's core packages is that they depend on each other and functionality is much too often spread over at least 3 different packages. That's not the case for gloss.

[MrTango]

I like the idea of Gloss, thats what many people are doing by them self, but in a convenient way, which make the life of new themers even easier.

I think the Glossy-rules should be either integrated into Barceloneta, which also means that the HTML templates of Barceloneta should use them, so we will have a change here or we build a new theme package which is based on Barceloneta but has Gloss already integrated. If we want to the first, we should do this as soon as possible as @djay mentioned. The second way will result in the new Gloss-theme will replace Baceloneta as default in the future.

[MrTango]

If the Gloss-template has the same structure as Barceloneta + some CSS-Classes it should be possible to not break any existing theme which is based on Barceloneta. So add the Gloss-Classes, shipping the Gloss-rules file and update them theming documentation should be enough.

We could do this already for the training in Boston.

If other changes of the HTML-template are needed to integrate it, we could provide a second HTML-template which uses the Gloss-CSS and structure. But i don't know if this is needy, maybe @pigeonflight can answer this question.

[jensens]

The PLIP got not the necessary votes by the framework team and was rejected. The code is anyway very valuable and can perfectly live as an addon.

You may want to rethink the integration, this does not mean future PLIPs get rejected.

[Rudd-O]

Gloss would have been nice, but the theme makes even a basic site render quite slowly: https://github.com/GlossProject/gloss.theme/issues/26