John, Thanks for the feedback, but seriously, you come off pretty negative in your approach. Keep in mind that the tutorial you just read was contributed by volunteer(s) (not only myself). We ask for review of these documents frequently, and often have sprinters who are new to TurboGears go through the tutorials and correct them for mistakes. While I agree we need to be careful in keeping our documentation, most of us lack the time to comb every bit of the existing tome to check for accuracy. Currently there are about 4 main developers on the TG2 team, and with the recent releases, we are just trying to keep pace with the code changes. That being said, if you would personally like to participate by validating and correcting our documentation, it would be much appreciated. The code for the sphinx doc is in the public repository here: http://svn.turbogears.org/docs/2.0/docs/main/ToscaWidgets/forms.rst and patches are always welcome. I encourage you to support our sprint on Jan 10th and 11th. Feel free to bring along some of the programmers you oversee.
Now, as for the pylons.c form thing. There was a lengthy discussion about this on IRC, and I believe in this group, but I cannot find it. The revelation is that the forms themselves are not data, and therefore should not be returned from the controller as such. Putting them in the template "C"ontext is makes much more sense from the model, view, controller paradigm. What you have to understand is that TG2 is very much integrated with Pylons, so the new TG2 developer would be wise to familiarize themselves with Pylons, as the TG1 developer would with CherryPy. I think we should probably change the tutorial to import tmpl_context instead of pylons.c and use that, as it would probably be more clear. Nevertheless, the people writing the initial docs for forms did so at a time when tmpl_context did not exist. I can give you utmost assurance that the forms tutorial will be up-to- snuff by pycon09, because both mark and I are giving tutorials involving forms, my tutorial is more tightly coupled with Toscawidgets, and Ajax. It is my hope that the forms tutorial will be replaced with a dbsprockets declarative tutorial, as they are much easier to use. Hope that clears a few things up. cheers. -chris On Dec 15, 9: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 --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
