[Grok-dev] Re: Skinning/themeing
optilude at gmx.net
Sat May 19 09:31:51 EDT 2007
>>> class MyView(quarry.View):
>>> """<html metal:use-macro="context/@@master/page">
>>> <body metal:fill-slot="body">
>>> <span tal:replace="structure provider:myviewlets" />
>>> 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.
template = grok.PageTemplate("""\
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):
>>> quarry.name('myviewlets') # provider:myviewlets
>>> class MyViewlet_10(quarry.Viewlet):
>>> 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):
> 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?
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?
More information about the Grok-dev