[documentation] Forms API handbook volunteer

Steven Jones darthsteven at gmail.com
Thu Mar 5 15:24:03 UTC 2009


So maybe we need to organise the top level, so we'd have:

1. Form API
1.a  High level - why use FormAPI
1.b  Form API basics
1.c  Advanced Form API

1.a Would be long pages of prose, explaining the why and a little of the how.

1.b This might take the form of a series of well written tutorials,
showing the basics, explaining things like nested $form arrays.

1.c This could be the place to chuck the examples, 'here's how I did
this' kind of code. I think these have the lowest barriers to entry,
so people will be more likely to write these. No?


Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites

Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk



2009/3/4 George <g at 8vue.com>:
> i'd like to suggest a simple starting outline for fapi
>
> 1/ intro - what is fapi, why not use html? security, consistency, etc
>
> 2 a/a basic input field - a description with example of basic textfield
> 2 b/properties of the textfield input (including #default_value)
>
> 3/ a simple form - putting the above example into a form, with a submit
> button. perhaps using system settings form and explaining why it's so cool!
>
> 4/ other input fields - pointing to the ref sheet, and also mentioning
> the other most used inputs and properties.
> 4 b/ buttons
>
> 5/ callbacks - outline of form building function, validation, submit for
> element and form
> 5 b/ drupal_get_form - how to use it in page callbacks for module dev
> 5c /example of simple module with formbuilder, form validation, element
> validation, form submit? (no db stuff, just using comments in the module
> to suggest like for the submit function // this is the action of the
> form, and we now know values are safe to work with, and can be inserted
> into the database, or acted upon
>
> 6/ what functions you shouldn't call directly
>
> 7/ ...
>
>
>
> Steven Jones wrote:
>> Hey everyone,
>>
>> I'm wondering if anyone wants to meet up at Drupalcon to discuss this,
>> maybe at the documentation sprint?
>>
>> The task of documenting FormAPI is a massive challenge, but I like the
>> idea of documenting examples, explaining the ways that the examples
>> work, and what they do.
>>
>>
>> Regards
>> Steven Jones
>> ComputerMinds ltd - Perfect Drupal Websites
>>
>> Phone : 0121 288 0434
>> Mobile : 07951 270 026
>> http://www.computerminds.co.uk
>>
>>
>>
>> 2009/2/27 George <g at 8vue.com>:
>>
>>> i'd like to suggest, examples. ie. a simple fapi array gives what type
>>> of element / form?  a lot can be inferred from a simple example that
>>> would take many more words. and the example only needs to cover the
>>> point of the example, so, if you're discussing setting up a textfield,
>>> then no need to create the whole form, just that element.
>>>
>>> also system_settings_form is a great helper function ;)
>>>
>>> i also think the reference chart for fapi is a great resource once
>>> you've got the basics.
>>>
>>> thanks
>>>
>>> Sameer Siruguri wrote:
>>>
>>>> Steven,
>>>>
>>>> the feedback I have seen on different forums is not very detailed --
>>>> it's mostly of the sort, "I wish there were more
>>>> detailed/comprehensive documentation about forms."
>>>>
>>>> One proposal I have is that we start putting something out there and
>>>> see how people react to it, sort of a wiki style of doing it, where we
>>>> incorporate comments over time once there is something to comment to.
>>>>
>>>> Alternatively, we could canvas some of the people who have commented
>>>> on various Drupal related websites about the difficulty of getting
>>>> comprehensive documentation and ask what they are lacking.
>>>>
>>>> I think the spectrum will be fairly wide in terms of expertise people
>>>> who are looking for Forms docs already have, but I wouldn't be
>>>> surprised if many of them are newbies trying to get to grips with the
>>>> basics. As Nancy notes, there will also be people looking to do
>>>> dynamic elements and multi-stage forms.
>>>>
>>>> One idea I had was to first create the detailed description of
>>>> _everything_ the API does, and then write an FAQ for some of the
>>>> common-case tasks, that point to entries in the detailed description.
>>>>
>>>> Thoughts?
>>>> Sameer.
>>>>
>>>>
>>>> On 2/27/09, *Steven Jones* <darthsteven at gmail.com
>>>> <mailto:darthsteven at gmail.com>> wrote:
>>>>
>>>>     Essentially, before launching into the massive effort of documenting
>>>>     FormAPI, we should have the discussion: 'What should we document'.
>>>>
>>>>     You mention: "lots of folks have been commenting on the lack of
>>>>     something good". What are they after? Are they newbies getting to
>>>>     grips with forms? Are they experienced developers wanting to do more?
>>>>
>>>>     Can anyone suggest what the FormAPI docs should cover?
>>>>
>>>>
>>>>     Regards
>>>>     Steven Jones
>>>>     ComputerMinds ltd - Perfect Drupal Websites
>>>>
>>>>     Phone : 0121 288 0434
>>>>     Mobile : 07951 270 026
>>>>     http://www.computerminds.co.uk
>>>>
>>>>
>>>>
>>>>     2009/2/26 Sameer Siruguri <siruguri at gmail.com
>>>>     <mailto:siruguri at gmail.com>>:
>>>>     > Steven,
>>>>     >
>>>>     > good to hear from you. I cannot make DrupalCon in DC, more's the
>>>>     pity. I am
>>>>     > interested in learning more about your views on how to properly
>>>>     document the
>>>>     > Forms API. Did you mean to say that the outline written by
>>>>     Steven Peck is
>>>>     > the one you have some doubts about? Or just the general style of the
>>>>     > content?
>>>>     >
>>>>     > I am interested in getting content out there asap, lots of folks
>>>>     have been
>>>>     > commenting on the lack of something good. Personally, I think
>>>>     having an
>>>>     > explanation of the steps inside drupal_get_form (process,
>>>>     prepare, alter,
>>>>     > render, etc.) would be very useful, esp. for ninja developers.
>>>>     It's easy to
>>>>     > get things mixed up if you don't know the exact order in which
>>>>     these steps
>>>>     > are called, including the parts where weights get sorted out,
>>>>     and when
>>>>     > pre/post_render functions get called.
>>>>     >
>>>>     > I would love to discuss some of these over email, if that's
>>>>     possible, or of
>>>>     > course, to hear more about what you learn at DrupalCon.
>>>>     >
>>>>     > Cheers!
>>>>     > Sameer.
>>>>     >
>>>>     > On 2/26/09, Steven Jones <darthsteven at gmail.com
>>>>     <mailto:darthsteven at gmail.com>> wrote:
>>>>     >>
>>>>     >> Hi Sameer,
>>>>     >>
>>>>     >> I actually was just the last person to edit that page, the
>>>>     content is
>>>>     >> down to Steven Peck.
>>>>     >>
>>>>     >> In any case I'm not sure that documenting FormAPI like that is the
>>>>     >> best way to go. Like you I've wanted to document FormAPI better
>>>>     for a
>>>>     >> while now, but I'm not sure the best way to approach it. Maybe we
>>>>     >> could gather a few interested parties at Drupalcon D.C. and have a
>>>>     >> little chat about the best way forward.
>>>>     >>
>>>>     >> Are the any other's who'd be interested in helping out with
>>>>     FormAPI docs?
>>>>     >>
>>>>     >> Regards
>>>>     >> Steven Jones
>>>>     >> ComputerMinds ltd - Perfect Drupal Websites
>>>>     >>
>>>>     >> Phone : 0121 288 0434
>>>>     >> Mobile : 07951 270 026
>>>>     >> http://www.computerminds.co.uk
>>>>     >>
>>>>     >>
>>>>     >>
>>>>     >> 2009/2/26 Sameer Siruguri <siruguri at gmail.com
>>>>     <mailto:siruguri at gmail.com>>:
>>>>     >>
>>>>     >> > Hi,
>>>>     >> >
>>>>     >> > I have been interested in fleshing out, and collating, the
>>>>     documentation
>>>>     >> > for
>>>>     >> > the Forms API for some time now, and recently got started on
>>>>     writing out
>>>>     >> > the
>>>>     >> > material that would go under the headings that Steven Jones
>>>>     wrote out on
>>>>     >> > this page: http://drupal.org/node/204270 (Here's a page I
>>>>     wrote, with
>>>>     >> > one
>>>>     >> > child: http://drupal.org/node/384120)
>>>>     >> >
>>>>     >> > Here's the problem I ran into: After writing some pages down, I
>>>>     >> > sheepishly
>>>>     >> > realized that some material already existed as child pages.
>>>>     But I don't
>>>>     >> > have
>>>>     >> > edit permissions to the top level of those child pages, which
>>>>     makes it
>>>>     >> > hard
>>>>     >> > to incorporate some of my changes and esp. to consolidate all the
>>>>     >> > material
>>>>     >> > at the top level.
>>>>     >> >
>>>>     >> > Here are some solutions: I could go ahead and build out all
>>>>     the material
>>>>     >> > and
>>>>     >> > then propose a consolidation. I could build it on my own
>>>>     website and
>>>>     >> > find
>>>>     >> > some way to export the book to be imported into Drupal.org. I
>>>>     could have
>>>>     >> > access to the top level pages. I could do something during
>>>>     DrupalCon.
>>>>     >> >
>>>>     >> > I am open to suggestions. Thanks!
>>>>     >> > Sameer.
>>>>     >> >
>>>>     >> >
>>>>     >>
>>>>     >> > --
>>>>     >> > Pending work: http://drupal.org/project/issues/documentation/
>>>>     >> > List archives: http://lists.drupal.org/pipermail/documentation/
>>>>     >> >
>>>>     >> --
>>>>     >> Pending work: http://drupal.org/project/issues/documentation/
>>>>     >> List archives: http://lists.drupal.org/pipermail/documentation/
>>>>     >
>>>>     >
>>>>     > --
>>>>     > Pending work: http://drupal.org/project/issues/documentation/
>>>>     > List archives: http://lists.drupal.org/pipermail/documentation/
>>>>     >
>>>>     --
>>>>     Pending work: http://drupal.org/project/issues/documentation/
>>>>     List archives: http://lists.drupal.org/pipermail/documentation/
>>>>
>>>>
>>>> ------------------------------------------------------------------------
>>>>
>>>> --
>>>> Pending work: http://drupal.org/project/issues/documentation/
>>>> List archives: http://lists.drupal.org/pipermail/documentation/
>>>>
>>> --
>>> Pending work: http://drupal.org/project/issues/documentation/
>>> List archives: http://lists.drupal.org/pipermail/documentation/
>>>
>>>
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>


More information about the documentation mailing list