[documentation] Forms API handbook volunteer
George
g at 8vue.com
Thu Mar 5 23:33:36 UTC 2009
no, don't restrict just examples to one section, use them throughout as
one may use a diagram. heck why not even compare an html form with a
fapi form in the introduction? and don't over do the 'why use fapi'
section, short and to the point.
verbosity is the enemy!
just my opinion!
Steven Jones wrote:
> 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/
>>
>>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
More information about the documentation
mailing list