I agree, and created a trac ticket to clean up the form tutorial here: http://trac.turbogears.org/ticket/2061
This is slated to be done before 2.0b1, and hopefully will be done in the next couple of days. --mark On Mon, Dec 15, 2008 at 11:44 PM, John M Camara <[email protected]> wrote: > > 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 > > > -- Mark Ramm-Christensen email: mark at compoundthinking dot com blog: www.compoundthinking.com/blog --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
