FormAPI: better handling of programmatic submission

#parameters' purpose is to store *what is necessary to reconstitute the form* at another point.

$args isn't necessarily just the array-shifted version of the initial arguments. By the time #parameters is populated, it's also been merged with any hard-coded parameters specified in the hook_forms() function.

Why is that important? If we store a copy of *the original args passed into the function* we can feed #parameters straight back into drupal_retrieve_form to reconstitute a copy of the form. If we use the 'final' copy of $args, #parameters would be almost useless -- we couldn't use it with any of the core form functions, and we'd have to manually call the builder function.

I'll be adding a few lines of documentation to the code later this morning, but the code itself shouldn't change, IMO.

Attached is a re-rolled patch with a comment explaining the purpose of #parameters, and why func_get_args() is used rather than $args.

chx noted that drupal_execute() was irretrievably clobbering the return value of drupal_process_form(). We usually won't need that when programmatically processing a form, but it's impossible to recover that value after it's lost. It IS possible to call form_set_errors() after processing, though, so the redirect return value should win. Patch rerolled.

1. Why are the final arg values different from the original ones?

#parameters is, essentially, "what would have to be passed into drupal_get_form() to pull this form up again."

In cases where a given form id is mapped to a separate builder function using hook_forms(), drupal_retrieve_form() adds the callback arguments from the hook_forms() entry into the $args list. The full combined args list is passed to the form builder function. For example:

function mymodule_forms() {
  $forms['myform_id'] = array(
    'callback' => 'my_form_builder',
    'callback arguments' => node_load(arg(1))
  );
}

function mymodule_page() {
  print drupal_get_form('myform_id', 'bob');
}

function my_form_builder($node, $name) {
  // in this example, $node will contain the argument from hook_forms() 'callback argument'.
  // $name will contain the parameter passed in by the drupal_get_form() function.
}

This is rather complex. But it's what allows us to alias multiple form IDs (some with slightly different callback arguments) to a central builder function. Like some of the other more esoteric properties, the only real solution is to either stop doing complicated things with forms, or duplicate a LOT of code between very similar forms, introducing many other errors along the way.

2. Why do we want to reconstitute a copy of the form?

We do it in multiform scenerios by packing logic inside of drupal_get_form(). This parameter just allows other module code the opportunity to get at the same 'original parameters list' drupal_get_form() sees. It's a key requirement for Adrian's form-recording and playback workflow system, and it opens up opportunities for other modules to access more core data baout the formAPI system. It also doesn't break anything. ;)

If the #parameters thing is really a sticking point, I'm more than willing to pull it out. I suppose that it could, if really necessary, be turned into its own one-liner patch in a separate issue.

Could you upate the documentation (at the top of the file) with a valid example that uses the extra paramater passing options that drupal_execute() has?

creating a new node is one example, though it's a little ugly because the node system itself requires some funky parameters. I'll look around for a good example that doesn't get too complicated. (Creating a new user is very clean, thus very convenient for demo use).

drupal_execute() sounds weird. Maybe drupal_post() or drupal_submit() is better? (Not sure, not important at this point.)

I went round and round on this; it's hard to find a descriptive function without trampling on or overloading functions we already use in the form workflow. The reason I settled on execute(), after a lof of discussion in #drupal, was because it uses the formAPI system but opens the doors for using in ways that aren't 'forms' at all, like Jaza's import-export system.

Maybe I'm the only one here, but I find the form handling pretty darn hard to grok. Imagine the day, we loose our form API experts ... and we're left with something like the menu system ...

This is indeed a problem. I think the biggest areas of 'voodoo' right now are form_builder (because of the tremendous amount of work it does), the multistep form feature (because only a handful of peopel have used it), and hook_forms(). They're all necessary, but they are either super-complicated or very new.

Are there any 'hot spots' of mysteriousness that you can see? I've been neck-deep in forms for a month or two now, and while the workflow is something I feel I can confidently understand and explain now, I'm sure that I'm missing bits that are confusing to a casual peruser.

rerolled against HEAD.

Code is expensive, comments are cheap. There are now two simple examples of programmatic submission at the top of form.inc: adding a new user and creating a new node. One uses no parameters, the other (the node form) requires one. The chunk is as follows:

 * Forms can also be built and submitted programmatically without any user input
 * using the drupal_execute() function. Pass in the id of the form, the values to
 * submit to the form, and any parameters needed by the form's builder function.
 * For example:
 *
 * // register a new user
 * $values['name'] = 'robo-user';
 * $values['mail'] = 'robouser@example.com';
 * $values['pass'] = 'password';
 * drupal_execute('user_register', $values);
 *
 * // Create a new node
 * $node = array('type' => 'story');
 * $values['title'] = 'My node';
 * $values['body'] = 'This is the body text!';
 * $values['author'] = 'robo-user';
 * drupal_execute('story_node_form', $values, $node);
 *
 * Calling form_get_errors() after execution will return an array of any
 * validation errors encountered.

Hopefully, with Adrian's explanation re: the #parameters array, and the additional comments, this is RTBC. :)