[Grok-dev] Notes about the tutorial

Fri Jun 1 11:39:45 EDT 2007

Yesterday I read through the Grok Tutorial for the second time and
made some notes of things I think could be improved. Most of them are
minor, but I also propose some structural changes.

Using view methods
------------------------------------------

- The "Unassociated templates" sidebar mentions a problem that has not
ocurred so far in the tutorial, because the Bye view is still in the
app.py module at this point. It should be moved to the end of the
section.

- When the code below is shown as a shorter alternative, the string
"Hello world!" inside the <p> element should be kept as in the
previous example.

<html>
<body>
<p tal:content="view/current_datetime"></p>
</body>
</html>

The rules of persistence
------------------------------------------

Something's missing in this sentence:

"""
You will also notice a small change to the update method of the Edit
class. Instead of just storing the text as an attribute of our Sample
model, we add each text we enter to the new list attribute on.
"""

A second model
------------------------------------------

This an example to introduce the grok.context() and grok.name('index')
view annotations, but the example is so contrived that the need for
the annotations is really not justified in my mind. Also, I did not
like the fact that the app.py module that was built so far is replaced
by one that does less. I would defer the explanation for these
annotations to the next section, "Containers", when the sample app
actually needs to use them.

Containers
------------------------------------------

When the __init__ method of Entry is shown, we should explicitly say
that for grok.Model subclasses it is not necessary to invoke the
superclass __init__ method as it is for grok.Containers subclasses as
stated in the section "The rules of persistence".

***********

A question: are all root classes of Grok apps subclasses of
grok.Application and grok.Container, or is it possible (and useful) to
derive only from grok.Application? Comming from a Zope 2 background,
it seems natural to me that an app is also a container, but I wonder
whether this is also natural for people not used to the Zope way.

A suggestion: I thought of a simple app that could evolve from the
examples in the tutorial. I like the adding machine theme of some of
the first examples, and we could keep following it. Instead of
appending text lines in the example which starts in "The rules of
persistence", we could append floats to a list, and the sum could be
shown in index.pt. In the next iteration, the Entries would be
expenses, with a description and a value, producing an expense report.
Finally, expenses could be linked to different users, and the system
could be used by friends organizing a picnic to calculate the end
balances for settling the expenses. This could even evolve into an
application of the classic bank accounts Smalltalk example, showing
how purely OO Grok is.

Numbering the sections and listings in the tutorial would make it
easier to talk about them. I volunteer to do that.

I have started developing the adding machine example, but have
stumbled into some basic error.

Next message I'll ask about that...

[ ]s
Luciano