Saturday, December 28, 2013

Diazo theming is great, now we need a snippets library

TL;DR: Diazo is how theming should be done, you can even integrate new functionality into your site via a Diazo theme but be responsible and aware when doing so. XSLT makes Diazo more powerful but can be complex, a library of useful Diazo snippets could go a long way in making Diazo more approachable.

Just checked out +Nathan Van Gheem's rethemed site. His blog post is worth reading. He basically purchased a theme and used a few Diazo rules to make it work with Plone. He even went as far as integrating Disqus into his site using only Diazo rules, no touching of the underlying CMS code.

I like.

Adding functionality to your site via Diazo is a powerful thing but be careful, if you need to switch themes you'll need to add the functionality again or risk "breaking" your site. Diazo does leave your site vulnerable to sins of omission. Leave something out of your new theme that was previously in your old theme and you've lost it (until you put it back). One possible solution is to have themes that promise a minimum implementation, e.g. all valid themes might promise to include footers, menus, themed portlets and breadcrumbs.

Diazo is really a wrapper around an XSLT engine (I hope I'm understanding it correctly), the Diazo directives hide a lot of the underlying XSLT and generally make transforming your site more friendly. However, like Nathan, I've found that taking advantage of "raw" XSLT in my Diazo themes gives me more power, the price I pay is a more verbose file. Though raw XSLT is powerful I think it adds a barrier of entry to the average CSS guy. One way to lower the barrier is to document how common transformations are achieved using  Diazo and XSLT through some kind of snippets repository.

Below is a simple example of transforming a portlet using XSLT into markup suitable for a Bootstrap 3.x based template.

Before and After: The portlet on the left has been transformed using XSLT with Diazo

And here's the Diazo rule (with lots of XSLT) used to achieve it. The resulting transformation is elegant but requires a understanding XSLT and the related XPATH if you needed to construct it from scratch.
<!-- transform all portlets -->
<replace css:content=".portletWrapper">
<div class="pWwrapper">
<div class="portletWrapper">
<xsl:attribute name="data-portlethash"><xsl:value-of select="@data-portlethash"/></xsl:attribute>
<div class="panel panel-default">
    <xsl:for-each css:select=".portletWrapper > dl">
        <div class="panel-heading">
          <xsl:copy-of select="dt/node()"/>
      <div class="panel-body">
       <xsl:for-each css:select="dd">
            <xsl:if test="@class[contains(.,'portletFooter')]">
              <xsl:attribute name="class">panel-footer footer</xsl:attribute>
          <xsl:copy-of select="node()"/>

Diazo is how theming should be done. I now feel that Diazo as a theming framework is almost there*. It's good enough for persons willing to invest in understanding XSLT but will be helped along the way with a good snippets library.
* I'm aware that in some way, passing judgement like this, may oblige me to contribute somehow to the improvement of the Diazo ecosystem.


Nathan Van Gheem said...

Great writeup. FWIW, Thijs Jonkman has a lot of great Diazo examples with some pretty clever XSLT transformations.

David Bain said...

Thanks Nathan, so the first (low hanging fruit) would be to just gather all the useful XSLT transformation examples that already exist.

Pieter B. Ruiter said...

Your posts on diazo and plone have been *invaluable* for me. After working through your Step-by-step document and reading up on xslt/xpath, this xslt example is now quite readable. Thanks!

ps: I'm sure there must be scenarios where you would strip the plone output like this, but would in not also be possible/easier to copy the portlet with all those dd/dl/dt's and format with css?

David Bain said...

Thanks for the feedback Pieter. My general approach nowadays is to aim to benefit from modern CSS from "pattern libraries" like Bootstrap. I assume they've taken the time to do things the "right" way. So for that reason I don't mind fiddling with the XSL to make my markup match their styles. Rather than fiddling with the CSS to make it look right.

Plus I'm very allergic to that dd/dl/dt markup

Sign up for my upcoming Plone 5 Book & Video tutorials

plone 5 for newbies book and videos