[prev in list] [next in list] [prev in thread] [next in thread]
List: drupal-documentation
Subject: Re: [documentation] Forms API handbook volunteer
From: Steven Jones <darthsteven () gmail ! com>
Date: 2009-03-06 14:07:57
Message-ID: f27865f50903060607g1f5a017cwbd58b03137c8f037 () mail ! gmail ! com
[Download RAW message or body]
George, don't hear me wrong! I'm not saying that we shouldn't use
examples in the other sections, but rather the last section should be
example driven. I.e. Each child page would be an example of some
specific thing using FormAPI.
The other sections could and should use examples, but would be focused
of explaining some specific portion of FormAPI, possibly using an
example.
Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites
Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
2009/3/5 George <g@8vue.com>:
> 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@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@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@gmail.com
>>>>>> <mailto:darthsteven@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@gmail.com
>>>>>> <mailto:siruguri@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@gmail.com
>>>>>> <mailto:darthsteven@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@gmail.com
>>>>>> <mailto:siruguri@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/
>>
>
> --
> 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/
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic