[documentation] Forms API handbook volunteer
George
g at 8vue.com
Fri Feb 27 23:15:20 UTC 2009
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/
More information about the documentation
mailing list