Today someone asked me a question about adding a form to a TG 2 app
and since I haven't touched TG in over a year (only because I don't
get to program much these days, I just oversee other programmers) I
decided that I better look at the docs before answering the question
expecting things would have changed by now.
For a tutorial that should be aimed toward beginners I was surprised
by the number of mistakes in the doc. Anyone new to programming
wouldn't have much of a chance making it through it successfully. I
don't have time to fix the doc at this time although I may do so over
the next few weeks as I feel it's an important doc to be correct to
improve the rate at which TG 2's gets adopted.
I'm not going to bring up all the errors I have found right now as I
didn't pay too much attention to the whole doc as I mostly looked at a
small section of it but want to bring up a few points in that area.
In the definition of the form template the following line is there to
render the form:
${tmpl_context.form()}
The code for the controller is
# we tell expose which template to use to display the form
@expose("genshi:toscasample.templates.new_form")
def new(self, **kw):
"""Form to add new record"""
# Passing the form in the return dict is no longer kosher, you can
# set pylons.c.form instead and use c.form in your template
# (remember to 'import pylons' too)
pylons.c.form = model_form
return dict(modelname='Movie')
Simple enough I understand what's going on. Although it makes me have
some questions and wonder how puzzled a newbie would be by looking at
the code.
pyons.c in the controller gets transformed to tmpl_context? WTF What
newbie or even experienced programmer new to TG is going to make that
connection. Now because I realize the form needs to be passed to the
template and that I happened to know that the c in pylons.c stood for
context it didn't take me too long to make the connection. Maybe it
would be better to get rid of the tmpl_context from the template an
instead require the line in the template to be written as
${pylons.c.form()}
That way people learning TG have a decent chance of making the
connection. Is there some reason why pylons.c was not chosen.
Now I also have an issue with the following line
pylons.c.form = model_form
The issue here is form in pylons.c.form is a bit to generic for an
attribute name. Especially in a tutorial as a new user may think oh
when you want to add a form just use the following idiom
pylons.c.form = some_form
But what happens the day they need two forms on a template. Now it's
very easy to pass to forms to a template as you just need to do the
following
pylons.c.some_form = some_form
pylons.c.another_form = another_form
But from the example the user has no way of knowing that the attribute
named form could have been any name. Now had that line been written
as
pylons.c.new_movie_form = new_movie_form
It would be obvious that your just adding attributes to the pylons.c
object. Now another issue I have is with the following comment from
the controller
# Passing the form in the return dict is no longer kosher, you can
# set pylons.c.form instead and use c.form in your template
# (remember to 'import pylons' too)
Why are forms special and not passed in the return dict. Now I can
let my imagination go wild and can think of a number a reasons why
that may be a requirement but there is nothing in that comment or in
the surrounding text that explains why it's necessary to treat forms
in a special way. One is left wondering whether or not there are some
other special cases I need to worry about.
Now I'm sure there is a good technical reason why forms are a special
case, but for someone new it's going to seam like some black magic is
going on here. With the example cleaned up a bit and some additional
background information the user will have a better understanding of
TG.
Just think of the novel I would have wrote had I actually commented on
the whole tutorial rather than just a few lines of it. :)
John
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TurboGears Trunk" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/turbogears-trunk?hl=en
-~----------~----~----~----~------~----~------~--~---
