[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