cow-tents: A debugger for Diazo

Comments
by Jamie Lentin on Nov 11, 2012

This is something I've been sporadically working on for quite some time now, and it's starting to take shape. When writing themes, I've found the main headache is working out which expression isn't matching. Is it the css:content, or the css:theme? This should make it much easier.

Caveats

This is all a bit rough-and-ready, but I think it's got to the point that other people could try it out with their themes and see if they find it useful.

Installation

To use it, you'll need the freshly-released 1.0.3 version of Diazo, and my branch of plone.app.theming. Add the following to your buildout config:

 [sources]
plone.app.theming = git https://github.com/lentinj/plone.app.theming.git branch=diazo-debugger

And check it out:

./bin/develop co plone.app.theming
./bin/buildout

Now, go to a themed page and add ?diazo.debug=1 to the URL. You should see an overlay containing debugging output.

Debugger screenshot

What am I looking at?

The output should be your theme file, after all includes have been included.
All diazo attributes and rule tags have been coloured red and green. A green attribute means that it matched the theme/content XML, a green node means all the attributes within match. For example:

Debugger line 1

The content has a base node, but the theme doesn't have one, so this rule won't do
anything.

Debugger line 2

The content is missing the edit bar, so the rule doesn't do anything either.

Debugger line 3

Both sides do something, so this rule is green and the title should have been copied.

Debugger line 4

Here everything within the append rules match, but the rules block they are within doesn't, so they are still red.

Errors

If your theme doesn't compile at all, you have probably noticed that you get an unthemed page without any hint of what went on. Now the XML / XSLT errors that you'd otherwise have to dig out of Plone's error log are in the overlay.

xsl:message tricks

The debugger considers each rule and condition in isolation. It will tell you when a CSS condition isn't matching. However it won't tell you when the rule isn't doing anything due to other rules, for example a drop rule could remove what an append rule appends to. xsl:message and the error log helps us here though. Compare the two examples, with the drop rule working:

Debugger xsl:message 2

...and the drop rule broken:

Debugger xsl:message 1

The <xsl:message> doesn't add anything to the document, however it will add messages to the error_log, which we can now see in the debug window. Ideally we would inject similar messages for the debugger to pick up. This is how it currently works after all---special messages saying what conditions matched are put out on the error_log and then combined with the rules XML. However, this is a lot more invasive change than what has been done so far, and some rules will be trickier than others.

What else needs to be done

You probably noticed it needs more styling. But everything has a lot of classes, so hopefully this will just be CSS work.

Outputting the compiled XSLT would also be very useful for debugging. The back-end side of things is fairly easy, however the overlay needs tabs so this could be displayed on the page in a manageable fashion. With the XSLT appended to the end, the scrollbar would be very long.

Please give it a go and tell me what you think! Is there bugs with some themes? Does it make your life easier, or at least more colourful?

blog comments powered by Disqus