Ticket #11880 (closed PLIP: fixed)
Ship with plone.app.theming
Reported by: | ldr | Owned by: | ldr |
---|---|---|---|
Priority: | n/a | Milestone: | 4.2 |
Component: | General | Version: | |
Keywords: | Cc: | optilude |
Description (last modified by jonstahl) (diff)
Proposer: Laurence Rowe
Seconder: None as yet
Motivation
Theming in Plone is too hard, it requires knowledge of complex underlying technology (the component architecture) which does not come easily to HTML/CSS developers.
Diazo allows themers to create themes without needing to understand the underlying technology.
plone.app.theming / plone.resource also allow template to be customized and simple new views created by simply placing templates in a directory for filesystem themes, see here.
Simple Diazo themes can be packaged as zip files and uploaded into a live running zope.
Assumptions
This proposal is to ship with plone.app.theming as an optional install.
Not in scope for this PLIP
Only theme directories on the filesystem and not those in the ZODB (from unpacked zip files) may include templates at this time. Additional work is required for portal_view_customizations to support view customizations in a ZODB plone.resource folder.
There is currently no good way to setup CSS / JS registry regisrations from a theme. Supporting this will require significant changes to ResourceRegistries and is considered outside of scope.
Proposal & Implementation
Final releases of plone.app.theming and plone.resource will be required. The only missing feature required for a 1.0 release is the addition of an option to set the output doctype. This will be implemented in repoze.xmliter as a simple string regex replacement.
Deliverables
- plone.app.theming
- Integration package, an evolution of collective.xdv.
Dependencies
The following packages will be introduced
- 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. 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.
- experimental.cssselect
- Improved CSS to XPath functionality currently part of lxml trunk and to be released in 2.3.1. (Expected to be removed before final release.)
- lxml
- libxml2/libxslt wrapper
- plone.resource
- Publishes directories of static files via the ZPublisher. These directories may be located either in the ZODB (as OFS folders and files), or on the filesystem.
- plone.subrequest
- Simple Zope subrequests
- plone.transformchain
- Hook into repoze.zope2 that allows third party packages to register a sequence of hooks that will be allowed to modify the response before it is returned to the browser
- repoze.xmliter
- Used to pass lxml trees efficiently through the transform chain.
- z3c.jbot
- The z3c.jbot (or "Just a bunch of templates") package allows easy customization of existing templates and images. It works on Zope 2 and Zope 3.
Test dependencies
- WebOb
- For diazo WSGI middleware.
Risks
- plone.app.theming and plone.resource are not yet out of beta
- the z3c.jbot support is new.
What incompatibilities can it cause?
Participants
- Laurence Rowe
- Martin Aspeli
Progress
Currently in beta we have already seen several new themes based on the technology uploaded to plone.org.
Change History
comment:2 follow-up: ↓ 6 Changed 5 years ago by jonstahl
- Description modified (diff)
Friendly amendment: I think it would be very "integrator approachable" to have our installers configure a global filesystem resource directory by default, e.g.
[instance] zcml-additional = <configure xmlns="http://namespaces.zope.org/zope" xmlns:plone="http://namespaces.plone.org/plone"> <include package="plone.resource" file="meta.zcml"/> <plone:static directory="${buildout:directory}/resources" /> </configure>
comment:3 Changed 5 years ago by jonstahl
Also: the docs at http://diazo.org are fantastic, but I think there is probably more to do around "getting started/best practices" for plone.app.theming with Plone. Not sure whether this should live at diazo.org, or, more likely somewhere on plone.org, with reference to diazo.org, but in any case, I think that documents targeted at first-time Plone themers should be an acceptance criteria for this PLIP.
comment:4 follow-up: ↓ 5 Changed 5 years ago by hannosch
Does plone.transformchain actually depend or use repoze.zope2? Or does it integrate with Zope 2's native WSGI functionality?
comment:5 in reply to: ↑ 4 Changed 5 years ago by optilude
Replying to hannosch:
Does plone.transformchain actually depend or use repoze.zope2? Or does it integrate with Zope 2's native WSGI functionality?
It *can* use repoze.zope2 (and originally used it), but in regular Zope 2 it uses publisher events to do the transformation. There's no explicit repoze.zope2 dependency (and we probably want to rip this out eventually).
Martin
comment:6 in reply to: ↑ 2 Changed 5 years ago by ldr
Replying to jonstahl:
Friendly amendment: I think it would be very "integrator approachable" to have our installers configure a global filesystem resource directory by default, e.g.
[instance] zcml-additional = <configure xmlns="http://namespaces.zope.org/zope" xmlns:plone="http://namespaces.plone.org/plone"> <include package="plone.resource" file="meta.zcml"/> <plone:static directory="${buildout:directory}/resources" /> </configure>
With the release of plone.recipe.zope2instance 4.1.6 we can now use the "resources" option. See http://pypi.python.org/pypi/plone.recipe.zope2instance#theme-resources
comment:8 Changed 5 years ago by alecm
Hello plone.app.theming developers. I've taken the task of championing this PLIP, and would like to initiate a conversation about the goals and scope of this PLIP.
After a long discussion among the Framework Team, there is some concern regarding the expanded scope of this PLIP. In particular it's not clear whether it makes sense to allow jbot based template customization in the context of a Diazo theme package, and it's especially unclear if we should be incorporating an entirely new configuration mechanism for declaring browser views.
I suspect that plone.app.theming as it existed in 1.0b4 would have easily been approved for inclusion, but the features added in 1.0b5 seem to blur the line between "theming" and "customization". Those new features came as a surprise to everyone involved in the discussion.
It's clear that Plone's theming and customization stories both need a significant overhaul. It's also pretty clear that Diazo is an appropriate and reasonably well vetted solution for many theming problems. It's not clear however that these new plone.app.theming features, which include non-theming features, are the best solutions for the customization side of things.
Could you describe the motivation for these new features, and perhaps tell us where you think the customization vs. theming line belongs (if there should be a line at all)? Do you believe this is the best way to incorporate jbot into Plone? What advantages does the new browser view configuration language offer over what we have now? Who is the intended audience for these features and are they implemented and documented appropriately for that audience?
comment:9 Changed 5 years ago by optilude
Hi,
From my perspective (Laurence may want to add his own thoughts):
- The 'views' support is not so much about creating new views for content types or forms or anything with real logic in it. It's intended to be used mainly with the 'href' support in Diazo: you can define a template that e.g. creates some complex markup to build a custom navigation structure (i.e. something not easily done using XSL on the markup coming out of Plone). If you're developing a theme on the filesystem in a resource directory, then you'd need to create a Python package and fiddle with buildout and learn ZCML. This feels quite "z-shaped". With the 'views' support, you just put a zpt in a directory. The ini file support is optional and only needed for special cases (e.g. you need a non-public view or you need to restrict its context).
- The 'overrides' support is similar. The jbot approach (monkey patching notwithstanding) is significantly easier and more integrator friendly than trying to do a ZCML override for a view (which is not only complicated, it's difficult to discover *what* to override in the first place). Again, the audience here is people who are building a theme and need to override e.g. a viewlet template to extract a bit more information out of Plone for e.g. navigation or other places where an XSL based transform would be too complicated or impossible (because the underlying data isn't being rendered in Plone).
That said, I can certainly understand the concern. I don't think the ini file syntax is the main issue, because I think that's an edge case only (most people won't need to use it) and is consistent with the basic mainfest info (for which we decided an XML format would be too convoluted, both to use and to implement).
However, both 'views' and 'overrides' are written as plugins and live in a sub-package plone.app.theming.plugins.*. We could spin this out into a separate package (or packages) and people could opt into it.
Note that I have a slightly different constraint here: the 1.0b5 approach to 'overrides' is described in Professional Plone 4 Development and that chapter has just gone to production. I've halted it for now, but I need to sort this out this week. I'd be happy to add a description of how to install an optional plugin package for the relevant example to work.
It would be useful if the plugins package remained part of the KGS, though, so we could make sure they'd always work together.
Martin
comment:10 Changed 5 years ago by ldr
I don't think that there exists a clear line between theming and customization. Martin's custom navigation example is a good one. While Plone certainly could develop a content 'API' that exposed all data in an HTML document, meaning any theming task could then be achieved with XSLT, I'm not convinced it would be a good idea! Creating markup with ZPT is generally simpler than XSLT.
The main advantage of the 'new browser view configuration language' is that in the common case of adding a template based view with the zope2.View permission requires no configuration at all. Assuming plone.app.contentlisting gets included, a simple view template might simply be::
<ul id="menu">
<li class="menuItem" tal:repeat="item context/folderListing">
<a tal:attributes="href item/absolute_url"
tal:content="item/title_or_id" />
</li>
</ul>
The intended audience for these features is the same as plone.app.theming, integrators looking to create a theme for their website. They may not come from a programming background, but dropping a template into a directory is the standard way of making theme customizations in systems such as Wordpress, so it should be familiar to them. In the long run I expect we will develop TTW tools as well.
Reference documentation already exists (on the pypi page) and narrative documentation will be in the book. I expect more narrative documentation will be written by the time it is released, I certainly intend to blog about it.
comment:11 Changed 5 years ago by hannosch
My 2cent: I think we should include plone.app.theming without any views or overrides support. These features might be well intended, but they have seen zero usage and feedback from the community and especially from the themers they are intended for. Let's not rush in yet another half-solution to customization.
The customization story needs to get better, but it needs a whole lot of more work. From speaking with Denys and my own experience in our projects, we never do themes with just template overrides or class-less views. We do use z3c.jbot in every single project, though to override some aspects of things like the author profile page, the comments viewlet, the language selector or other pieces of functionality. But we also have new portlets, new content types, changes to a whole lot of GenericSetup data in every project. Since we need a policy package anyways, we can keep all customization aspects to it.
For now I would keep the customization story and theming story completely separate. The next aspect we should move from customization to theming is sane registration of resources like CSS/JS files. This is a hard problem, but one that should be in the theming domain. Doing this while retaining, caching, minimization and merging support for resources coming from add-ons, Plone core and the theme itself is a challenge. Providing a good way to specify the absolute ordering of the files and excluding some is yet another.
comment:12 Changed 5 years ago by optilude
As I said, I'm pretty happy to spin this out into a "plugin" package that's not in Plone core. However:
- We need to decide on that before this weekend, please ;-) (this is driven by the book deadline, which I appreciate is a bit selfish of me, but I think it's in the community's interest for it to be correct for as long as possible)
- I'll probably continue to recommend people use this approach to build themes with associated template overrides.
I'd like some kind of framework team comment on this if we can.
Whilst the (very thin) integration of z3c.jbot into p.a.theming's resource directories is new and somewhat untested, z3c.jbot itself is very battle tested and popular, and by far the most sane approach we have for casual template overrides.
Given a choice between recommending people do "manual" z3c.jbot registrations (which means a hard need to build a package and register it in their buildout) and having the same convention-based approach available without ZCML boilerplate, I prefer the latter.
Martin
comment:13 Changed 5 years ago by ldr
At this point I think moving those features to another package is the right thing to do. However I do think that the approach has merit. The target audience here are not highly experienced developers who are already building python packages for all their projects, but those people who might be able to customize a few templates through the web or add one in portal_skins. Having some way of exporting these to the filesystem is really important as it provides a stepping stone to more advanced Plone development involving python code and products.
comment:14 Changed 5 years ago by optilude
Ok - I've now released http://pypi.python.org/pypi/plone.app.themingplugins which contains the views and overrides plugins. As of plone.app.theming 1.0b7, those are no longer part of plone.app.theming itself.
The KGS at http://good-py.appspot.com/release/plone.app.theming/1.0b7 does contain a known good version of plone.app.themingplugins. I think it would be good if we kept that in the KGS when this moves into Plone, just to help people who want to use it keep versions in sync.
However, we don't need to install plone.app.themingplugins with Plone and we don't need to "advertise" it either.
comment:15 Changed 5 years ago by robgietema
Can a buildout be created at: http://svn.plone.org/svn/plone/buildouts/plone-coredev/branches/4.1/plips/ with only the packages which will be included in for this plip?
comment:16 Changed 5 years ago by ldr
comment:17 Changed 5 years ago by ldr
comment:18 Changed 5 years ago by ldr
comment:19 Changed 5 years ago by alecm
comment:20 Changed 5 years ago by optilude
A couple of comments in response to the review:
"- The package profile is titled "Diazo Theme Support" and the control panel is called 'Diazo Theme'. This seems like it might be a poor usability choice. These titles should endeavor to be as clear and jargon free as possible."
What would be a better name? Agree these are not all that great, and there may be further confusion since we have another Theme control panel!
"- When a theme is applied, the ZMI will be themed (and generally entirely blank) unless special precautions are taken in the theme rules to avoid it."
One way to fix this would be to make something in the ZMI set the X-Theme-Disabled response header, which turns off plone.app.theming's transform. I'm not sure if there's anything sufficiently common in the ZMI to do this. In the past, we've used URL exclusion patterns, but they get quite convoluted and/or brittle.
Re coverage in the plugins module: There was indirect coverage, but then we moved all that code to p.a.themingplugins. ;-) I can't recall whether there is much to test that's actually left, though perhaps we could test with a fake plugin or something like that.
On the last point on documentation, note that Professional Plone 4 Development will cover Diazo theming with p.a.theming and call it "best practice". diazo.org also has a good amount of docs, as does the p.a.theming PyPI page.
Cheers, Martin
comment:21 Changed 5 years ago by jonstahl
Martin,
Can the Diazo Theme control panel be merged with the existing Theme control panel somehow?
comment:22 Changed 5 years ago by alecm
Martin,
I made a few naming suggestions in the conclusions of the review 'Theme packages' or 'HTML Themes' or 'Theme add-ons'. However, I am not the best person for deciding such things. Merging it with the existing control panel as Jon suggests might work, but that would require making the package a bit less independent.
I agree the plone.app.theming and Diazo pages provide decent best practices documentation, but looking at themes already out in the wild, they're not being followed consistently (i.e. the ZMI issue). So we have to make sure that wherever people go to copy/paste their basic rules file from has all the basics in place (and the book doesn't count for this purpose, since plenty of people without the book will need a basic rules template). As a precaution for the ZMI, it would probably be safe to skip theming on manage_* urls.
There seems to be quite a bit of code in the plugins package, and those subscribers are being called frequently, so it would probably be a good idea to have some direct tests.
comment:23 Changed 5 years ago by optilude
Hi Alec,
A lot of those themes were started before that documentation was ready (or the patterns were even decided). ;-)
The problem with not theming manage_* URLs (apart from the fact that there's not really a way to do this outside the rules.xml file) is that manage_* does not capture all of the ZMI. It'd be better if we found a base class or something we could patch to set X-Theme-Disabled.
Agree on tests, though I'm not sure I'll personally have time in the near future. I'll put it on my list to look at if no-one else gets to it, though.
Martin
comment:24 Changed 5 years ago by alecm
I understand, but a lot of people will be basing their themes on those themes, so documentation will be important.
Well, there's certainly no base class for the ZMI. Though isn't some if it still DTML? :-) I think manage_* is as close as you'll get.
In any case, it's my opinion that it's ready for merge. My concerns are minor and not really worth debating at length :-)
comment:25 Changed 5 years ago by esteele
- Status changed from new to closed
- Resolution set to fixed
I'm finishing up the PLIP for including LXML (static libxml2 & libxslt) with the Unified and OS X installers. Sidnei has already got it in the Windows installer. So, there will be no barrier there.