[drupal-devel] Forms API conversion help

[Apartment Lines]

chris, thanks for writing in about this.  atm, i'm sort of the point person
for forms API doc.  it's a big task, but we're slowly making progress!

first thing to note is that even though the form you're converting seems
simple, there are a few tricky parts to it.

so...

1. i'd specify the #action at the root of the form tree, like so:
$form['#action'] = request_uri();  Also, the '#fieldset' attribute is making
everything in the tree under $form['subscribe'] into a form group--is that
what want?  If your goal is to get those div tags in the right place, you
can just place them at the right spot in the form tree using the #markup
attribute.  for this form that's how i'd handle it, and just scrap the
entire ['subscribe'] layer of the form tree.

2. yep, #markup it is.  WHAT_GOES_HERE? is where the name of the markup
element goes.  since this isn't getting passed to $_POST['edit'], you can
name it whatever you like.  remember $form['foo'] means that the value will
be available under $_POST['edit']['foo']

3. the easy answer is: '#type' => 'hidden'.  the more complete answer is,
depends...  :)  under the new forms API, the 'correct' way to submit a form
is writing a form execute function (instead of the old $op/switch approach).
if you do write a form execute function, then you want to use '#type' =>
'value'.  this has the nifty benefit that the hidden fields don't get output
as HTML.  forms magic!

4. you build those arrays like this now: (and i'm hacking out your
['subscribe'] layer as i mentioned above)

$form[ezmlm_list]['#tree'] = TRUE;
$form[ezmlm_list][trim($list_text)] = array('#type' => 'checkbox', '#title'
=> trim($list_text));

in this case, you don't need to declare #return_value explicitly, because
form code already has this as a default for the checkbox form element, and
i'm *pretty* sure the same applies to #default_value

the big tricky part of this section of code is that you need to preserve
that tree structure in $_POST['edit'].  by default, the form code squashes
it, meaning that $form[ezmlm_list][trim($list_text)] will appear in POST as
$_POST['edit'][trim($list_text)].  oops, you lost the [ezmlm_list] layer...
:)

to preserve the full tree for that section of the form array, you need to
set the tree attribute to TRUE, which is what i did in the above section of
code.

5. for drupal_get_form, the first arg is the form_id for the form--it's a
string and the convention so far has been to name the form based on the
function that it's created in.  so for this form, it would be:

return drupal_get_form('_ezmlm_subscribe_form', $form);

hope this helps  :)

and if anything still doesn't work, let's talk about it at drupalcon...

chad



Chris Wrote:

I am in the process of trying to convert the ezmlm module to the new forms
API.  I am doing this so I can learn the forms API.  I am one of the
maintainers of the ezmlm module and it is a very, very simple module.

Once I learn the forms API fairly well, I will be happy to help other people
with their conversion efforts, write more documentation on the API and/or
convert more modules.  I just need to get it all clear in my head first.

However, I'm having some problems converting a simple form in my module.  I
spent several hours reading all the latest documentation and working on it
last night, and I've run into a few things where I am not clear on how it
should work.

If anyone is willing to give me some help, you can view the before and after
code here:

http://phpfi.com/82366

Questions:
1. Is the #action key in the first form[] element the right way to specify
where to post the form?

2. What's the proper array element index where it says "WHAT_GOES_HERE" for
a
non-form item message that needs to be injected into the form at that point?
Is #markup the right type?  Seems like it is.

3. What's the correct #type for my hidden form element?

4. What's the correct form array secondary index for an array of checkboxes?
In the old form API, one used names like 'my_checkbox_list][' in order to
generate HTML like this:
		<input type="checkbox" name="edit[my_checkbox_list][]">
How is that done with the new API?


Thanks,
Chris Johnson
31 hours until I leave for Amsterdam!  :-)