I mean the more documentation the better but I was kind of hoping to keep the documents kind of centralized or at least with a sort of table of contents. Otherwise we end up with the gaps that the current docs have.
-Ian On 2/8/07, Mark Ramm <[EMAIL PROTECTED]> wrote: > > 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 -~----------~----~----~----~------~----~------~--~---
