[documentation] Forms API handbook volunteer
George
g at 8vue.com
Wed Mar 4 09:26:08 UTC 2009
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/
>
More information about the documentation
mailing list