After getting back into Drupal 5.0 development, I have spent a lot of time ranting about how I find the most recent version of Form API hard to work with. People keep asking me what is "wrong and what to do about it. So far, I have not actually been able to articulate what really bugs me, overall it is just a feeling that I am constantly fighting the API and not creating code.
Having spent some time thinking about it, I think I am starting to get an idea of what bugs me.
The Cruft
Due to being massive arrays quickly seeing how a form is built is frustrating. This might be something I master over time as I spend more timing creating these form arrays, but for now I miss the old days when this:
$form['selected'] = array('#type' => 'select',
'#title' => t('Selected'),
'#options' => array('0' => t('No'), '1' => t('Yes')),
'#default_value' => $edit['selected'],
'#description' => t('Set this to Yes if you would like this category to be selected by default.'),
);
Was this:
$form .= form_select(t('Selected'), 'selected', $edit['selected'], array(t('No'), t('Yes')), t('Set this to Yes if you would like this category to be selected by default.'));
The old 4.6 forms I can right away tell that this form element is a select element, and the order is consistent!
Consistency
This brings me to the other thing that drives me nuts, it is that while Drupal has pretty consistent and enforced coding standards when it comes to PHP, there are no rules for formatting of these form arrays. This also applies to menu arrays, another very important part of Drupal that I spend far too much time re-reading all the code to find that one menu item I want to alter (search is thy friend I suppose).
General formatting of the arrays is all over the place. Sometimes each key => value pair in the array is all on separate lines, sometimes they are all on one incredibly long line, sometimes there are more than one pair per line until it reaches some undefined limit.
In addition, the ordering of the pairs is all over the place. Since it is an array the order of the arguments do not matter, whereas for the old form_* functions there was one way to do it, and once you learn it was the same.
For me this means I spend a lot more time scanning each form element to find out what it is doing compared to the old form_* functions where you scan for the function being used and after that everything is just where you expect it to be. With the arrays you end up scanning for #type, which may or may not be the first pair, may or may not be on its own line or hidden in the middle of 10 other pairs.
At the very least, I would love it if there were a Drupal Way of doing forms that was set in the coding standards and strongly enforced for core. As it is, each form I look at it is as if I have to figure out which standard out of potentially infinite variants is in use before I can dig in and dissect how it actually works.
Documentation
The flexibility and lack of standards brings me to the final point that is documentation. For the old form_* functions documentation was relatively easy as any developer with half a brain could find the function definition and read the arguments and not have to resort to further documentation. The array syntax does not lend itself well to that, since there is no real function definition. All the possible values in the array is "hidden" in several functions related to the Form API, which is actually relatively complex with a lot of conditionals and loops.
Currently most of the documentation is for 4.7 Form API, and still needs to have some serious overhaul for 5.0. It could also benefit from a lot more examples and HOWTO style documents.
Bringing it all together
So far I have found mastering forms difficult because the formatting is inconsistent making the already crufty syntax harder to scan and due to the documentation not representing all that Form API can do.
Forms being one of the corner stones of the web and a content management platform should be so easy to create and get into. It really should not have to require mastering some of the more complex code in Drupal.
Maybe I will feel differently in a few weeks when I have more experience with the new system, but on some level, I think my observations are true.
