Re: [drupal-devel] Forms API documentation update
Another update. Tonight, Kieran, Károly, and I worked on http://drupal.org/node/37194 which presents a flowchart and code example comparing the "old" forms API with the new one, for those who are more "visual" in their learning approach. Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture." I've also added the following pages since the last update: * Forms API FAQ: http://drupal.org/node/36899 * Tips and Tricks: http://drupal.org/node/36900 These are intended to be places where developers can post comments as they think of questions, or come up with neat things that helped them, and myself and/or Chad will go through the pages periodically and incorporate comments into the text. Feel free to post comments anywhere else within http://drupal.org/node/33338 where it makes sense too... your feedback is greatly appreciated! Finally, project module took a bit longer than previously anticipated to convert, but it's done now, so I will work to get that tutorial out aoon. :) -Angie Angie Byron wrote:
Chad and I have made some good progress on Forms API documentation tonight:
1. Centralized all forms documentation under the "Upgrading to forms API" part of the handbook: http://drupal.org/node/33338
2. Placed an initial "overview" page which covers the "why?" of the forms API, to help people understand its importance.
3. Added an "errata" section to the handbook, to cover bugs with the current forms API which have not yet been patched, so check here first if you're having difficulty getting your forms to work. If you come across any other issues, please feel free to post them there. I will keep an eye on the handbook queue and endeavor to get the page updated as quickly as possible (or just ping me on IRC, I'm usually around).
4. Mapped out a plan for two additional supporting documents: the first, a step-by-step tutorial on how the project module was converted from the old way to the new (of course it needs to be finished first, working on it!! ;)), and the second a comparison of various examples from core of varying difficulty with before and after code. Both are slated to be completed by the end of the day Monday.
5. Added the Forms API QuickStart guide and Forms API reference to drupaldocs.org (this was already done actually but I figure I will mention it here anyway ;)). There are a couple updates pending for these pages (translation to the new array indentation standard, fixing of the two #weights problem in the reference doc, adding a legend to the table, fixing up the internal links, etc.) which should show up the next time drupaldocs.org is updated. The "live" version of these docs are always available from here: http://cvs.drupal.org/viewcvs/drupal/contributions/docs/developer/topics/
6. Created a temporary workspace to coordinate completion of the remaining docs (located here if you're interested: http://drupaldev.snarkles.net/wiki/index.php/Main_Page -- I know, I know, I should be using Drupal for this, but it is only temporary and MW is just really well-suited to this kind of thing). Here you can check status to see how it's coming along, or even post something if you have time and are able to help.
If anyone else has additional comments on what documents you would find useful, what documentation you feel is lacking, etc. please feel free to let us know!
-Angie The Happy Drupal Forms API Documenter ;)
On Friday 11 November 2005 01:26, Angie Byron wrote:
Tonight, Kieran, Károly, and I worked on http://drupal.org/node/37194 which presents a flowchart and code example comparing the "old" forms API with the new one, for those who are more "visual" in their learning approach. Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture."
Nicely done, and very helpful!
* Forms API FAQ: http://drupal.org/node/36899
I have two concerns about this page. First, in one of the code snippets (inline), I think you have an "=" where you need "=>" for an associative array declaration. Also, you used some standalone constants (implied string constants, that is, strings without quotes), which might be syntactically valid, but which IMO are a little harder to read than putting those constants into quotes. Second, there is a paragraph that states that taxonomy forms no longer require any code in the application. That may be true for the simple case of a module that creates a custom node type, but it is emphatically not true in the general case of all modules. I've already ported one module that requires a taxonomy form, but where the module does not implement the node API. I can supply a code example of how I did it, if that would help. (I actually think I may have already sent my example to someone on the docs team, but maybe not.) There are a few cases where one needs a taxonomy form to select terms from a vocabulary or vocabularies, but where the module that needs the form is not the same as the module that defines the node type(s) in question. My image_import module is one such case. I could envision an "advanced search" type of module, or perhaps some kind of taxonomy/node statistical module, that would also encounter this situation. Kind regards, and thanks for your work so far. I intend the above to be constructive suggestions, not empty criticism, and I am willing to do what I can to contribute to the solution rather than just pointing out the problems. If I can be of assistance in doing so, please let me know. Kind regards, Scott -- ------------------------------------------------------------------------------- Scott Courtney Drupal user name: "syscrusher" http://drupal.org/user/9184 scott at 4th dot com Drupal projects: http://drupal.org/project/user/9184 Sandbox: http://cvs.drupal.org/viewcvs/drupal/contributions/sandbox/syscrusher
Angie Byron wrote:
Another update.
Tonight, Kieran, Károly, and I worked on http://drupal.org/node/37194 which presents a flowchart and code example comparing the "old" forms API with the new one, for those who are more "visual" in their learning approach. Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture."
I've also added the following pages since the last update:
* Forms API FAQ: http://drupal.org/node/36899 * Tips and Tricks: http://drupal.org/node/36900
Great job, guys and gals. Thanks much.
Moshe Weitzman wrote:
Angie Byron wrote:
Another update.
Tonight, Kieran, Károly, and I worked on http://drupal.org/node/37194 which presents a flowchart and code example comparing the "old" forms API with the new one, for those who are more "visual" in their learning approach. Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture."
I've also added the following pages since the last update:
* Forms API FAQ: http://drupal.org/node/36899 * Tips and Tricks: http://drupal.org/node/36900
Great job, guys and gals. Thanks much.
Absolutely. You all rock! Your dedication motivates me to do more for Drupal. ..chrisxj
Thanks to everyone for their dedication and perseverance on this effort. I want to name names, but I am sure I will forget someone, so thanks to all who participated.
A big THANK you too, from me. Great job! in the mean time: if you find anything related to formsAPI, rants on weblogs, kudos, posts in forums etc etc: http://del.icio.us/tag/formsapi I think it is good to collect all sorts of pages there, for example: http://del.icio.us/tag/formsapi+rant . It will help us understand what people think and want. Ber On Fri, 11 Nov 2005 09:42:28 -0600 Chris Johnson <chris@tinpixel.com> wrote:
Moshe Weitzman wrote:
Angie Byron wrote:
Another update.
Tonight, Kieran, Károly, and I worked on http://drupal.org/node/37194 which presents a flowchart and code example comparing the "old" forms API with the new one, for those who are more "visual" in their learning approach. Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture."
I've also added the following pages since the last update:
* Forms API FAQ: http://drupal.org/node/36899 * Tips and Tricks: http://drupal.org/node/36900
Great job, guys and gals. Thanks much.
Absolutely. You all rock!
Your dedication motivates me to do more for Drupal.
..chrisxj
On 11 Nov 2005, at 16:17, Moshe Weitzman wrote:
Angie Byron wrote:
Another update. Tonight, Kieran, Károly, and I worked on http://drupal.org/node/ 37194 which presents a flowchart and code example comparing the "old" forms API with the new one, for those who are more "visual" in their learning approach. Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture." I've also added the following pages since the last update: * Forms API FAQ: http://drupal.org/node/36899 * Tips and Tricks: http://drupal.org/node/36900
Great job, guys and gals. Thanks much.
Agreed! Once we feel comfortable with the forms API documentation, I'd like to issue a 'call for module updates' on drupal.org -- and point people to the forms API documentation. Anyone who wants to coordinate this? (Robert?) -- Dries Buytaert :: http://www.buytaert.net/
On Nov 10, 2005, at 10:26 PM, Angie Byron wrote:
Hopefully this will prove valuable for people who are struggling a bit with the "bigger picture."
A top priority for the Drupal community is training more Drupal developers. I hope this diagram will help developers come up to speed quickly. I know we have to train at least 400 Drupal developers who contribute to Drupal CVS and probably several times that who just write simple custom modules for their personal or client sites. This diagram, http://drupal.org/node/37194 , shows the difference between the old and new models of form processing. However, the challenge with the Forms API is not so much understanding the New Forms API but rewriting an existing form into an abstract model of creating arrays of value, performing validations, and form executions. I am concerned that capable Drupal developers are taking a long time to understand this shift, which means that casual developers are probably giving up. If anyone has ideas how to better explain porting modules (written, visual, examples, media) your insight would be appreciated. We have received really good feedback on the documentation so far, but still face a high barrier. Cheers, Kieran
participants (8)
-
Angie Byron -
Ber Kessels -
Chris Johnson -
Dries Buytaert -
Khalid B -
Kieran Lal -
Moshe Weitzman -
Syscrusher