Just need a place to post an illustration of the FAPI workflow to let some of the FAPI experts see if it's right.
The Open Office file for the illustration.
OK, new version attached. Note that I've done it under Windows OOo2.2, so fonts might be slightly different under Linux (things might be a tighter fit, is the most notable change).
1. I've stuck elements in blocks of pale grey, to sort of establish a more intuitive, higher-level framework. I'm not sure on the Prepare/Build boundary, but the rest of the blocks seemed pretty obvious.
2. I've gone for strong colour-coding as I think it's visually more useful e.g. in the Prepare block, you can now see the hooks really clearly
3. I've minimized a lot of repeated text ( (c) Edward Tufte, probably) to emphasize the function names while still permitting the whole function name to be extracted. Given that hooks are yellow, you don't need to be distracted by lots of "hook_" all over the place.
Hope this is all OK.
The file won't open, something is wrong with it.
Sorry about that. I've just downloaded it and renamed it as an odg file again; it opened fine. Do you get any useful information in the OpenOffice error? What version of OO?
I'm going away for the weekend tonight; I'll try and sort this out when I get back. If need be I can just create a replacement PNG if our OO versions are incompatible.
I'm using 2.0.2. It just brings up a dialog box saying it wants to send an error report to Sun, and a bunch of stuff about how the program crashed and it will send an error report if I agree, then it keeps trying to open over and over, crashing each time.
How weird. Sorry about the hassle.
Not sure what OOo2.x flavour I was on in the other office, but I'm on my Linux machine now (with OO2.2.0) so hopefully things will be a bit smoother. I've also now uploaded a couple of files to my own site, to avoid any possible encoding problems that might be going on during upload to here:
I've not done anything particularly clever with OO so I'm at a loss to explain the crashes, but see what you can do with the above. (Note: the fonts are a bit off now: OO under Linux puts the font sizes at maybe 5% larger than Win OO. That's why all the () at the end of functions have had to go. I can always stick them back in.)
@jp.stacey : your schema is neat and cool, but it seems to be mixing FAPI workflow and 'node form submission' workflow, which is likely to add confusion. If you're aiming at generic FAPI handling (for _any_ form), there should not be such things as 'save' and hook_nodeapi in the process.
@yched, this is his rework of what I did at http://drupal.org/node/165104 (we needed an issue to attach the OO file to since you can't attach it to book pages, so that's where this issue came from). I included nodeapi() in the chart because the purpose was to see all the points where the form values could be altered, which includes some of the nodeapi hooks. I've been using that as I work on converting the widgets to use FAPI in the 6.x port.
@jp.stacey, this time it worked for me, hooray! I like your changes very much. I'll replace my image with yours on the book page.
I can see that including nodeapi() might be confusing, but it really helps me to see where it fits into things.
@jp.stacey, for some reason I'm having trouble getting this into a jpeg file to put on the book page, can you provide one for me?
One more thought, if we change the title to say 'Form Handling' instead of 'FAPI Handling', would that make it less confusing to include nodeapi?
@KarenS: no problem. I've moved it round to fit better on the book page, as OpenOffice doesn't seem to let you export to different sized images without changing page dimensions.
I've exported to GIF and JPEG - best to use the GIF if possible as it's smaller and suited to crisp line drawings (fewer artifacts, although colour export from OO is crap even then: look at that dithering....)
I've added a new generic FAPI workflow illustration for Drupal 7.x on the wiki page https://drupal.org/node/165104. I've used the yEd graph editor. If needed I can post here the source file (yEd is freeware). Please have a look to the illustration.
Thanks for the nice work on documentation, however I'm not very sure why this is filed against date module. I'm happy to move this to 'documentation' if it is in date by mistake.
Just had a chat with @yched on IRC and confirmed that it is a candidate for documentation project.
Drupal is a registered trademark of Dries Buytaert.