Hello Hello, As the widget documentation saga continues I become more unsure about what people are actually expecting to exist. I have tried starting a document myself a few times and really it always is coming out as if I was intentionally obsuficating it. A lot of the details seem to be around in multiple documents but they always stop right before they hit the real complicated stuff. So I thought if anyone wasn't actually directly handling this that we should just start a thread and toss ideas around until we get something that makes sense and then I'll try to write that up.
First off I think we need two major documents. One that is just a boring reference of what core widgets are available and what they actually do. The docstrings have been upgraded a lot and so this should be easy to do even if its just a beautification/summary of the docstrings. People get scared when they see source, especially all that meta magic, although I've grown to love that magical source. The second document should be more of a what you would do in practice ie. "how to use this". I have made a sort of outline for this document but at times it breaks down. Maybe widget overview should be this document... I found it really hard to make an example that can be expanded as you go to engulf all the current functionality. Which is a big problem since a lot of good examples are missing from the current docs that could explain how all the components work together. Although some of the mentioned functionality has an existing document, like validators (FormValidationWithSchemas) and basic form usage(SimpleWidgetForm). 0.Introduction -link to reference -explain why widgets exist etc. 1.The Basics a.Overriding The Template(source style/package style) b.Where to initialize(ie. go over the stateless nature and how requests can walk over each other's data if you are not careful) c.How to display(using display() or that the widget instance itself is callable or using the python console) d.Using params (adding to widget, getting to the widget, how defaults are set) 2. Compound/Nested Widgets a.how to nest a widget inside another widget(defining the class, etc) b.how to get params to a nested widget (need to cover repetitions as well as just named widgets, ie. FieldSet as well as RepeatingFieldSet.. these are incredibly hard to understand at first and then seem stupidly easy once you start using them) 3. Form Widget + Validation -this is a little sloppy and inconsistent so it will be hard to explain, since validators and widgets are really not that related but _seem_ to be a.how validators are assigned to widgets(forms/schemas/inside forms) b.how a select field guesses validators(I don't really know how this works but there is something fishy here and it needs to be documented somewhere even if its just to say _always_ give them a validator or it doesn't work right) 4. Widget + JS/CSS a.source way/package way(similar to overriding template) b.go over retrieve_js/retrive_css and explain in detail how the master template must exist and the widgets must be in the uppermost level of the dictionary returned to the template for the magical inclusion to take place c. The form field id problem, one of the major reasons Tosca widgets exist even though for now i think we sohuldn't mention them(as to not overwelm new users) but only document the problem and work arounds(if we can come up with any) 5. Examples(We can pull a lot of this from a the old trac docs and then start getting rid of them) a.we need to display how you use all the core widgets(_actually_ use), my biggest pet peeve was it took me forever to figure out how to get options/repetitions to the right widget at display time, so maybe one uber form that does everything with validators would do it. Probably shouldn't say magical so many times but it seems that way. So does this fit the bill or is this not the type of documentation that is missing? yada yada yada -Ian --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears Docs" 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-docs?hl=en -~----------~----~----~----~------~----~------~--~---
