[Product-Developers] Re: Where does it hurt?

Dylan Jay gmane at dylanjay.com
Mon May 19 12:17:04 UTC 2008

Daniel Nouri wrote:
> Dylan Jay writes:
>> Martin Aspeli wrote:
>>> Hi guys,
>>> Following a long discussion with Dylan Jay (buried in another thread
>>> on Devilstick terminology), I thought I'd conduct an informal poll.
>>>  ==> As a customiser of Plone, or as someone wanting to build
>>> bespoke components that extend Plone, what do you find most
>>> confusing?
>>> I think this could fall into a few categories:
>>>  - Areas where there's insufficient/poor documentation, but once you
>>> learn how to do something, it's clear how to proceed.
>>>  - Areas where there appears to be more than one approach, and it's
>>> not clear which one to choose
>> We seem to have so many ways to connect things and therefore customise
>> things that people use lots of different commbinations which are
>> unexpected and hard to guess.
>> For instance, yesterday I was looking at plone.z3cform. This is
>> nothing to do with using that framework, just to do with how they came
>> to the conclusion to use a combinatio of macros, views, etc to wire in
>> default plone like templates to z3c.form (they use a template that use
>> macro calls that a browser view that finds the macros in one
>> template). So many links in the chain it was hard to follow how it was
>> meant to be used.
>> I think z3c.form uses adaptation to find templates as well.
> So sorry for hijacking this thread.  But I need to explain a bit here;
> there's two ways to assign templates to your form:
>   - set "template = ViewPageTemplateFile('form.pt')" in your form
>   - register the template via ZCML (as an adapter)
> Most often you'll find that the first approach works just fine.  Your
> 'form.pt' will typically want to use parts or the whole of the existing
> plone.z3cform macro, like this:
>   <metal:use use-macro="context/@@ploneform-macros/form" />
> And that's all there is to it.  If you don't specify a template for your
> form, it will fall back to this anyway.
> Granted that the way macros are declared and hooked up in Zope 3 /
> browser views is different.  But the template itself ('macros.pt' in
> this case) looks exactly the same as with macros that live in the skins
> folder.

It's great that you explained it and I didn't mean to pick on you. But 
my point is that understand z3 code can be really hard by trying to read 
it. at least to the untrained eye. Good documentation is always good but 
  are there ways we can make things easier to understand without when 
documentation fails us?

More information about the Product-Developers mailing list