[Grok-dev] Re: Skinning/themeing

Sat May 19 09:31:51 EDT 2007

Hi Kevin,

>>> class MyView(quarry.View):
>>>    """<html metal:use-macro="context/@@master/page">
>>>       <body metal:fill-slot="body">
>>>       <span tal:replace="structure provider:myviewlets" />
>>>       </body>
>>>       </html>
>>>      """
>>>    template = grok.PageTemplate(__doc__)
>> Yipes! I realise this is just an example, but the idea of using the
>> docstring like that feels very dirty. :)
> 
> I would submit that for short clips, what documents a view class
> better than the code itself? :)

I completely disagree. The use of __doc__ there is illogical.

class MyView(quarry.View):

     template = grok.PageTemplate("""\
<p>foo</p>
""")

That makes a lot more sense, and it's a lot clearer what that HTML does. 
In the example you gave, if I didn't realise __doc__ was being 
overloaded as input to a page template, I'd be scratching my head as to 
why you pasted HTML into a doc string.

>>> class MyViewlets(quarry.ViewletManager):
>>>    grok.context(MyView)
>>>    quarry.name('myviewlets') # provider:myviewlets
>>>
>>> class MyViewlet_10(quarry.Viewlet):
>>>    grok.viewletmanager(MyViewlets)
>>>
>>>    def render(self):
>>>        return "GROK SMASH..."
>> I assume these names are there for ordering? That really strains the
>> eyes, though. Why not something like:
>>
>> class MyFirstViewlet(quarry.Viewlet):
>>     grok.viewletmanager(MyViewlets)
>>     quarry.order(10)
>>
>>     ...
> 
> Actually, that's how I originally implemented it. In theory it seemed
> like a great idea, but when I actually started coding with it,
> viewlet class names seem to be too loosely connected to the
> ViewletManager. It was difficult to ascertain which classes, like
> ContactUs or Products 'belonged' to the Menu ViewletManager.

Why? If the viewlet manager is called MenuViewlets and you do 
grok.viewletmanager(MenuViewlets) then surely that's easy to see?

> So I started
> naming viewlets to relate to the ViewletManager. Menu1, Menu2,
> Menu3... at that point, I dropped the quarry.order() directive and
> just sorted by class name.

I'm only one voice, but in my opinion, this is exactly the kind of 
convention-over-configuration that Grok *must not do*. I feel quite 
strongly about this, so I'm going to argue for a bit. :)

At the moment, we have a few different CoC patterns in Grok, e.g.

  - Deriving from a particular type of class, e.g. grok.View, performs 
some registration (e.g. of your view class)

  - Naming view classes and templates the same associates them

We also have various declarative statements that you can make, e.g. 
about the context of a view or to set up local utilities or whatever.

We also have a few name-based conventions, e.g. in unit tests, where a 
method starting with "test" is a test. That's fine, since unit test 
classes are so limited in scope. But it's not a general principle on 
which to build functionality.

By and large, I can choose names that make sense semantically. As a 
developer, I hate with a passion frameworks that force me to bend over 
backwards to use the type of names the framework author liked (or, more 
likely, found convenient to code). Inferring *properties* of an object 
(in this case, the order of a viewlet in a viewlet manager) from its 
name black magic voodoo that is probably going to be hard to maintain, 
difficult to debug, and possibly hard to explain and document.

It also doesn't scale conceptually - what if we needed some other 
property, e.g. the permission of a viewlet? 
MyViewlet_10_p_zope_app_security_IView? :)

Even with one such convention, I'm not convinced that it scales. Let's 
say an application has a viewlet manager. Some package wishes to plug in 
something there. It gives a name MyViewlet_10. Another package comes 
along and wants to plug in another element, last, so it calls it 
Viewlet_999. Ooops, "MyViewlet_10" sorts before "Viewlet_999". So we can 
parse the name and either raise an exception if the name doesn't match 
the class name of the viewlet manger, or look for an underscore (which 
is against all our various naming conventions, by the way) and a number 
and ... I don't think this is a slope I'd like to slip down.

> For the record, my gut reaction is to avoid creating new grok
> directives. I think it shares the same dangers as creating too many
> new ZCML directives.

Why? Of course, too many of anything is not a good idea, but that's not 
really an argument for inferring properties of a component implicitly 
from its name.

>> That to me is bad convention-over-configuration. It's fine if names of
>> things are used to find related things (view name -> template name).
> 
> Yes, that's what it's for, to relate viewlet name -> viewletmanager name.
> This does bring up a good point, where is the line drawn for
> convention-over-configuration. I think that Martijn and Phillip have
> done a great job of deliberating this and I certainly defer to them in
> these aesthetic matters.

Completely. It's dangerous if we end up with a "too many cooks" feel to 
the framework. Maybe we need some high level guidelines of what type of 
CoC we want to have?

Martin