Wow, that's pretty much exactly what I was thinking, but hadn't written down yet.
My plan was sort of built around existing documents, and how to get us to somewhere reasonable, as quickly as possible. It looked like this: 1) Overview Fix up Widgets Overview to do a better job showing the basics of a single widget with CSS, Javascript and HTML elements. This doc should start out by discussing how to set attributes, params, how to instantiate a widget, pass it to the form, and display it on a page. I agree this page also needs content about Widget Statelessness. 2 Widgets and Forms Update Simple Widget Form to discuss up front the benifits of Form Widgets. Add information about how compound widgets work Add discussion how validation fits in here (With validation specifics in a validation document). In particular document how form widgets display validation errors. 3) Gather up documents like the Remote Form Widget doc, basic AutoComplete Docs, and whatever other widgets already have documentation in an "Examples of how to use Widgets" page. 4) Use the FooBall example to talk about building your own widgets. 5) Create a Widget Tips and Tricks document If other people are willing to help, I'm pretty confident that we I can get at least the first 4 of these documents in reasonable shape during the DocSprint. And if enough people are willing to help I think we might be able to get more examples written. --Mark Ramm On 2/7/07, Kevin Horn <[EMAIL PROTECTED]> wrote: > 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 > > > > > > > > > > > > > -- 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 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 -~----------~----~----~----~------~----~------~--~---
