Discussion:
Forms API handbook volunteer
Sameer Siruguri
2009-02-26 04:28:00 UTC
Permalink
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.
Nancy Wichmann
2009-02-26 05:42:06 UTC
Permalink
Join the docs team and you can do it.

Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.
Sameer Siruguri
2009-02-26 06:49:52 UTC
Permalink
Thanks for the prompt response!

I had forgotten that on an old request of mine for being on the Doc team,
which was closed, there was actually note saying I could re-open if I had a
reason for added responsibility -- which I now do. So I re-opened it, and
hopefully, this time I'll be part of the doc team.

Cheers,
Sameer.
Post by Nancy Wichmann
Join the docs team and you can do it.
Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.
No virus found in this outgoing message.
Checked by AVG - http://www.avg.com
Version: 8.0.176 / Virus Database: 270.11.3/1969 - Release Date: 2/24/2009
6:43 AM
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/
Steven Jones
2009-02-26 09:29:01 UTC
Permalink
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
Post by Sameer Siruguri
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/
zambiahomlessworldcup streetsoccer
2009-02-26 09:40:32 UTC
Permalink
Hi Friends,
l would like to help with information on the above mentioned subject.
looking forward to hear from you.
Yours
Post by Steven Jones
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
Post by Sameer Siruguri
Hi,
I have been interested in fleshing out, and collating, the documentation
for
Post by Sameer Siruguri
the Forms API for some time now, and recently got started on writing out
the
Post by Sameer Siruguri
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
Post by Sameer Siruguri
child: http://drupal.org/node/384120)
Here's the problem I ran into: After writing some pages down, I
sheepishly
Post by Sameer Siruguri
realized that some material already existed as child pages. But I don't
have
Post by Sameer Siruguri
edit permissions to the top level of those child pages, which makes it
hard
Post by Sameer Siruguri
to incorporate some of my changes and esp. to consolidate all the
material
Post by Sameer Siruguri
at the top level.
Here are some solutions: I could go ahead and build out all the material
and
Post by Sameer Siruguri
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/
Sameer Siruguri
2009-02-26 19:38:03 UTC
Permalink
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.
Post by Steven Jones
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
Post by Sameer Siruguri
Hi,
I have been interested in fleshing out, and collating, the documentation
for
Post by Sameer Siruguri
the Forms API for some time now, and recently got started on writing out
the
Post by Sameer Siruguri
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
Post by Sameer Siruguri
child: http://drupal.org/node/384120)
Here's the problem I ran into: After writing some pages down, I
sheepishly
Post by Sameer Siruguri
realized that some material already existed as child pages. But I don't
have
Post by Sameer Siruguri
edit permissions to the top level of those child pages, which makes it
hard
Post by Sameer Siruguri
to incorporate some of my changes and esp. to consolidate all the
material
Post by Sameer Siruguri
at the top level.
Here are some solutions: I could go ahead and build out all the material
and
Post by Sameer Siruguri
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/
Steven Jones
2009-02-27 13:20:22 UTC
Permalink
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
Post by Sameer Siruguri
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.
Post by Steven Jones
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
Post by Sameer Siruguri
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/
Nancy Wichmann
2009-02-27 14:24:46 UTC
Permalink
Post by Steven Jones
Can anyone suggest what the FormAPI docs should cover?
I could easily see this get to book length. What I would like to see is
practical examples that take people from basic forms on through to complex,
including multiple part and dynamic forms. I can probably contribute some
examples.

Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.
Steven Jones
2009-02-27 14:28:39 UTC
Permalink
If one were to write a book, would you buy it? :-)

Should the main bulk of the section be examples, with step by step
explanations then? So if you're looking to do XYZ you can find xyz
(that looks almost like it) and follow along?

Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites

Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
Post by Steven Jones
Can anyone suggest what the FormAPI docs should cover?
I could easily see this get to book length.  What I would like to see is
practical examples that take people from basic forms on through to complex,
including multiple part and dynamic forms.  I can probably contribute some
examples.
Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.
No virus found in this outgoing message.
Checked by AVG - http://www.avg.com
Version: 8.0.176 / Virus Database: 270.11.3/1975 - Release Date: 2/27/2009 7:05 AM
--
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/
Nancy Wichmann
2009-02-27 22:25:39 UTC
Permalink
Post by Steven Jones
If one were to write a book, would you buy it? :-)
If I had the money, there are several Drupal books I would buy.
Post by Steven Jones
Should the main bulk of the section be examples, with step by step
explanations then?
Yes, that's what I would suggest.

Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.

-----Original Message-----
From: documentation-***@drupal.org
[mailto:documentation-***@drupal.org]On Behalf Of Steven Jones
Sent: Friday, February 27, 2009 9:29 AM
To: A list for documentation writers
Subject: Re: [documentation] Forms API handbook volunteer

If one were to write a book, would you buy it? :-)

Should the main bulk of the section be examples, with step by step
explanations then? So if you're looking to do XYZ you can find xyz
(that looks almost like it) and follow along?

Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites

Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
Post by Steven Jones
Post by Steven Jones
Can anyone suggest what the FormAPI docs should cover?
I could easily see this get to book length. What I would like to see is
practical examples that take people from basic forms on through to complex,
including multiple part and dynamic forms. I can probably contribute some
examples.
Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.
No virus found in this outgoing message.
Checked by AVG - http://www.avg.com
Version: 8.0.176 / Virus Database: 270.11.3/1975 - Release Date: 2/27/2009 7:05 AM
--
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/
Sameer Siruguri
2009-02-27 21:21:29 UTC
Permalink
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.
Post by Steven Jones
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
Post by Sameer Siruguri
Steven,
good to hear from you. I cannot make DrupalCon in DC, more's the pity. I
am
Post by Sameer Siruguri
interested in learning more about your views on how to properly document
the
Post by Sameer Siruguri
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
Post by Sameer Siruguri
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
Post by Sameer Siruguri
get things mixed up if you don't know the exact order in which these
steps
Post by Sameer Siruguri
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
Post by Sameer Siruguri
course, to hear more about what you learn at DrupalCon.
Cheers!
Sameer.
Post by Steven Jones
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?
Post by Sameer Siruguri
Post by Steven Jones
Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites
Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
Post by Sameer Siruguri
Hi,
I have been interested in fleshing out, and collating, the
documentation
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
for
the Forms API for some time now, and recently got started on writing
out
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
the
material that would go under the headings that Steven Jones wrote out
on
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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/
George
2009-02-27 23:15:20 UTC
Permalink
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
Post by Sameer Siruguri
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.
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
Post by Sameer Siruguri
Steven,
good to hear from you. I cannot make DrupalCon in DC, more's the
pity. I am
Post by Sameer Siruguri
interested in learning more about your views on how to properly
document the
Post by Sameer Siruguri
Forms API. Did you mean to say that the outline written by
Steven Peck is
Post by Sameer Siruguri
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
Post by Sameer Siruguri
commenting on the lack of something good. Personally, I think
having an
Post by Sameer Siruguri
explanation of the steps inside drupal_get_form (process,
prepare, alter,
Post by Sameer Siruguri
render, etc.) would be very useful, esp. for ninja developers.
It's easy to
Post by Sameer Siruguri
get things mixed up if you don't know the exact order in which
these steps
Post by Sameer Siruguri
are called, including the parts where weights get sorted out,
and when
Post by Sameer Siruguri
pre/post_render functions get called.
I would love to discuss some of these over email, if that's
possible, or of
Post by Sameer Siruguri
course, to hear more about what you learn at DrupalCon.
Cheers!
Sameer.
Post by Steven Jones
Hi Sameer,
I actually was just the last person to edit that page, the
content is
Post by Sameer Siruguri
Post by Steven Jones
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
Post by Sameer Siruguri
Post by Steven Jones
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?
Post by Sameer Siruguri
Post by Steven Jones
Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites
Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
Post by Sameer Siruguri
Hi,
I have been interested in fleshing out, and collating, the
documentation
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
for
the Forms API for some time now, and recently got started on
writing out
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
the
material that would go under the headings that Steven Jones
wrote out on
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
this page: http://drupal.org/node/204270 (Here's a page I
wrote, with
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
have
edit permissions to the top level of those child pages, which
makes it
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
and
then propose a consolidation. I could build it on my own
website and
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
find
some way to export the book to be imported into Drupal.org. I
could have
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
access to the top level pages. I could do something during
DrupalCon.
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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/
Steven Jones
2009-03-04 03:45:10 UTC
Permalink
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
Post by George
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
Post by Sameer Siruguri
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.
    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
    > 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.
    >
    >>
    >> 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
    >>
    >>
    >>
    >>
    >> > 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/
George
2009-03-04 09:26:08 UTC
Permalink
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/ ...
Post by Steven Jones
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
Post by George
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
Post by Sameer Siruguri
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.
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
Post by Sameer Siruguri
Steven,
good to hear from you. I cannot make DrupalCon in DC, more's the
pity. I am
Post by Sameer Siruguri
interested in learning more about your views on how to properly
document the
Post by Sameer Siruguri
Forms API. Did you mean to say that the outline written by
Steven Peck is
Post by Sameer Siruguri
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
Post by Sameer Siruguri
commenting on the lack of something good. Personally, I think
having an
Post by Sameer Siruguri
explanation of the steps inside drupal_get_form (process,
prepare, alter,
Post by Sameer Siruguri
render, etc.) would be very useful, esp. for ninja developers.
It's easy to
Post by Sameer Siruguri
get things mixed up if you don't know the exact order in which
these steps
Post by Sameer Siruguri
are called, including the parts where weights get sorted out,
and when
Post by Sameer Siruguri
pre/post_render functions get called.
I would love to discuss some of these over email, if that's
possible, or of
Post by Sameer Siruguri
course, to hear more about what you learn at DrupalCon.
Cheers!
Sameer.
Post by Steven Jones
Hi Sameer,
I actually was just the last person to edit that page, the
content is
Post by Sameer Siruguri
Post by Steven Jones
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
Post by Sameer Siruguri
Post by Steven Jones
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?
Post by Sameer Siruguri
Post by Steven Jones
Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites
Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
Post by Sameer Siruguri
Hi,
I have been interested in fleshing out, and collating, the
documentation
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
for
the Forms API for some time now, and recently got started on
writing out
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
the
material that would go under the headings that Steven Jones
wrote out on
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
this page: http://drupal.org/node/204270 (Here's a page I
wrote, with
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
have
edit permissions to the top level of those child pages, which
makes it
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
and
then propose a consolidation. I could build it on my own
website and
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
find
some way to export the book to be imported into Drupal.org. I
could have
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
access to the top level pages. I could do something during
DrupalCon.
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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/
Steven Jones
2009-03-05 15:24:03 UTC
Permalink
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
Post by George
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/ ...
Post by Steven Jones
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
Post by George
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
Post by Sameer Siruguri
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.
    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
    > 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.
    >
    >>
    >> 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
    >>
    >>
    >>
    >>
    >> > 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/
George
2009-03-05 23:33:36 UTC
Permalink
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!
Post by Steven Jones
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
Post by George
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/ ...
Post by Steven Jones
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
Post by George
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
Post by Sameer Siruguri
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.
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
Post by Sameer Siruguri
Steven,
good to hear from you. I cannot make DrupalCon in DC, more's the
pity. I am
Post by Sameer Siruguri
interested in learning more about your views on how to properly
document the
Post by Sameer Siruguri
Forms API. Did you mean to say that the outline written by
Steven Peck is
Post by Sameer Siruguri
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
Post by Sameer Siruguri
commenting on the lack of something good. Personally, I think
having an
Post by Sameer Siruguri
explanation of the steps inside drupal_get_form (process,
prepare, alter,
Post by Sameer Siruguri
render, etc.) would be very useful, esp. for ninja developers.
It's easy to
Post by Sameer Siruguri
get things mixed up if you don't know the exact order in which
these steps
Post by Sameer Siruguri
are called, including the parts where weights get sorted out,
and when
Post by Sameer Siruguri
pre/post_render functions get called.
I would love to discuss some of these over email, if that's
possible, or of
Post by Sameer Siruguri
course, to hear more about what you learn at DrupalCon.
Cheers!
Sameer.
Post by Steven Jones
Hi Sameer,
I actually was just the last person to edit that page, the
content is
Post by Sameer Siruguri
Post by Steven Jones
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
Post by Sameer Siruguri
Post by Steven Jones
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?
Post by Sameer Siruguri
Post by Steven Jones
Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites
Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
Post by Sameer Siruguri
Hi,
I have been interested in fleshing out, and collating, the
documentation
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
for
the Forms API for some time now, and recently got started on
writing out
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
the
material that would go under the headings that Steven Jones
wrote out on
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
this page: http://drupal.org/node/204270 (Here's a page I
wrote, with
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
have
edit permissions to the top level of those child pages, which
makes it
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
and
then propose a consolidation. I could build it on my own
website and
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
find
some way to export the book to be imported into Drupal.org. I
could have
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
access to the top level pages. I could do something during
DrupalCon.
Post by Sameer Siruguri
Post by Steven Jones
Post by Sameer Siruguri
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/
Steven Jones
2009-03-06 14:07:57 UTC
Permalink
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
Post by George
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!
Post by Steven Jones
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
Post by George
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/ ...
Post by Steven Jones
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
Post by George
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
Post by Sameer Siruguri
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.
    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
    > 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.
    >
    >>
    >> 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
    >>
    >>
    >>
    >>
    >> > 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/

Loading...