[development] FormAPI 3: State of the Union

[Jeff Eaton]

The FormAPI 3 patch that landed early this month has added some  
significant capabilities to the API and smoothed out rough edges that  
have been around since Drupal 4.7. With the code freeze 4 weeks off  
we have a bit more breathing space, and I wanted to give folks a  
heads up on a small handful of high-importance FAPI patches that are  
still in the queue.

http://drupal.org/node/121620
This patch takes some of the hard-coded logic in form_builder() --  
the stuff that handles how form elements are populated from incoming  
$_POST values -- and allows each form element type to implement  
custom handling code in a function, not unlike the submit and  
validate functions. This sounds simple, but is a BIG advance towards  
simplification of CCK fields and custom element types.

http://drupal.org/node/146187
We've long juggled $_POST and $form_values when dealing with forms.  
This patch ensures that the raw post data is stored in $form_state in  
addition to the finessed $form_values. It also clarifies one of the  
tricky bits about drupal_execute() -- although it currently *says*  
that it takes a form values collection for processing, it REALLY  
treats that passed-in data like raw post values. With some complex  
forms, this causes odd issues. After this patch, drupal_execute()  
operates on $form_state['post'] for greater clarity.

http://drupal.org/node/146667
This patch is ginormous, but implements a very simple pair of  
changes. First, $form_state should always be the FIRST parameter for  
a form building function, rather than the LAST. Without this change,  
form building code triggered via a menu callback will break if bogus  
parameters are passed in after the normal path. In addition, it  
eliminates the legacy $form_values variable, and points people  
instead to always use the standard, always-available $form_state 
['values'] data.

Reviews and testing are appreciated; the quest to streamline the API  
continues. Hoorah!

--Jeff Eaton