[Grok-dev] Re: Grok nomenclature

[Martijn Faassen]

Martin Aspeli wrote:
[snip]
> The point is that we need a convention that's (a) visually appealing (b) 
> clear and (c) consistent, so that we don't end up with 100 different 
> ways of doing the same thing, making it hard to figure out what 
> components actually get registered when you work with a complex package 
> with potentially dozens of grokked things.

I think we should investigate a way to signal that we want 
auto-registration for existing classes (that you now register using ZCML).

That is, if you say:

from plone.app.portlets.portlets import base

class MyPortletAssignment(base.Assignment):
     pass

nothing happens. You register using ZCML or not at all; Grok won't care.

If you say:

import grok
from plone.app.portlets.portelts import base

class MyPortletAssignment(base.Assignment):
     grok.grokked()

It'll be grokked (if a grokker was registered for base.Assignment of 
course). 'grok.grokked()' just adds the IGrokked interface to these 
classes. You then are supposed to use directives where needed.

These directives can be defined by grok. In this case the semantics of 
these directives should be the same, or very similar, to the semantics 
of the directives as used in Grok ('grok.context()' should not suddenly 
be used to set the view name, say).

Sometimes you need domain-specific directives. Let's imagine you need a 
'pipeline' directive (purely imaginary), and this is entirely portlet 
specific. Then you'd do:

import grok
from plone.app.portlets.portlets import base

class MyPortletAssignment(base.Assignment):
     grok.grokked()
     base.pipeline("Whatever")

It should be clear to the reader of the code that this is a class-level 
directive - there's nothing else it could be doing, and people should be 
able to recognize class directives as they're well familiar with 
zope.interface.implements().

This will allow domain-specific extensions to the Grok language to be in 
their own namespace, and there won't be an explosion of classes, one for 
non-grok and one for grok, where this is not necessary. If ZCML can 
register it, one should be able to register it with Grok too.

The requirements for extensions to the Grok domain specific language:

* avoid there being a "ZCML class" and a "Grok class". No explosion of 
base classes. Of course if there's no base class at all yet for the ZCML 
case we are fine.

* clearly signal to the reader of the code that things are being grokked.

* don't expand the 'grok.' namespace. What's in there is defined by Grok 
(and five.grok follows that). Separate namespaces are a good thing, and 
monkey-patching import namespaces is bad.

* there being a way to evolve an application from the use of ZCML to the 
use of Grok, without changing everything at once.

* reuse grok directives where it makes sense

* introduce new directives where that makes sense, and import the 
directives from the same place as the base classes. I think these things 
should be semantically near.

If this means that you end up importing directives and base classes from 
10 different modules in a package, I think it's time to start 
refactoring the package and consolidating the places you need to import 
from into one.

Regards,

Martijn