Wow, you _have_ done a lot of thinking! This looks great! I have a couple of comments though...
0. Introduction I think this section is critical. It seems like a lot of confusion about widgets on the mailing list stems from the fact that people don't really understand what the TurboGears definition of widgets is. Some people think that they are just blocks of boilerplate HTML (they are more), and others think they are super-JavaScript-AJAXian replacements for typical desktop GUI controls (they are less...or at least different). Some good work here would clear up a lot of confusion, I think, and make the rest of the widgets docs easier to understand. 3. Forms, etc. One thing I think is necessary here is some discussion on how using form widgets can drastically speed up development. When I was just starting to mess with widgets (granted they were a lot less mature then) I didn't really grasp what I needed them for...until I found out that they would help me handle both server-side validation and that I could use the same form both for adds and edits. Now I cringe and groan whenever I have to develop a form in PHP, simply from all the boilerplate form HTML I have to write. TG has spoiled me in this regard, and I would like to see it spoil other people, too. :) 4. CSS/JS Definitely need some discussion on the way TG finds CSS/JS files, and how to put them in custom locations. This is a common question on the ML. 5. Examples I think this is the other really critical section if we want to draw users to TurboGears. And I totally agree that we need to have examples for _every_ core widget. Even though these will be a little tedious to write for people who have been using them for a while, it will make widgets vastly more accessible to new users. I also think that it will help pull together some of the disparate examples that are right now kind of all over the place. For example...when I was first learning widgets, I was trying to figure out how to use a select field and I had to go to one page for the basics, another page to figure out how to use a callable to generate my options list, yet another page to learn about the validator-guessing thing, etc... All in all, I think this is a great start! It seems to be exactly what I would be looking for if a) it was already written, and b) I was just learning TG. Kevin Horn On 2/6/07, Ian Wilson <[EMAIL PROTECTED]> wrote: > > > 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 -~----------~----~----~----~------~----~------~--~---
