FormAPI: Allow different buttons to fire different callbacks

Here's a slightly updated version of the function that cleans up some cruft in the $submit_values when loads of buttons are included in the form.

Only one code change is necessary with this patch:

function mymodule_form_alter($form_id, &$form) {
  $form['#submit']['my_additional_submit_handler'] = array();
}

becomes:

function mymodule_form_alter($form_id, &$form) {
  $form['#submit']['submit']['my_additional_submit_handler'] = array();
  $form['#submit']['preview']['my_additional_preview_handler'] = array();
  $form['#submit']['delete']['my_additional_delete_handler'] = array();
}

and so on.

Dries, here's a significant reworking of the patch by chx. I just ran it through some smoke-testing and it appears to be much much cleaner code-wise. hook_form_alter functions now attach their additional handlers *to the buttons themselves* rather than a global #submit operation.

More testing needed, but the technique seems much more consistent and much less kludgy than my above patch. Thoughts?

Fixed. There was a button-comparison that depended on behaviour that was removed in the $_POST['edit'] patch.

Had some funky issues after the most recent fapi patch. Re-rolled to prevent the offsets and confirmation questions in patch.

Updated for head. This is definitely a good candidate for 6, though we'll want to revisit the 'how this happens' discussion.

To recap, why is this useful?

Currently, we get one overridable callback -- submit -- for buttons. Previewing is tricky in part because it is a button click that executes *no* submit callback. Other buttons (like 'delete' and 'add more fields') all have to be overloaded in the 'submit' function.

This makes it far easier and far cleaner (from a module developer's perspective) to add many buttons that do different things. Just give each one a different callback, and implement a unique function for each one.

2. 'preview' and 'reset to defaults' do not have their own callbacks?
3. the %base handling is a bit of a hack, IMO.

Also, would it make sense to enforce a callback for each button? Right now, it looks like we're just adding another way of doing things rather than enforcing one way. Maybe it would be a good idea not to show buttons that lack a callabck?

Agreed -- this patch was originally conceived of near the tail end of 5.0's cycle, so there was an attempt to keep it as low-impact as possible. The changes you mention will probably clean things up quite a bit. We can take a look at them for the next roll of the patch.

Also, would it make sense to enforce a callback for each button? Right now, it looks like we're just adding another way of doing things rather than enforcing one way.

After a lot of thought, I think this might actually be the best approach. Or, at the very least, the only approach that wouldn't involve using #base as a wildcard character.

The downside would be that EVERY form submit button in core and contrib would need to add '#callback' = array('my_form_submit' => array());. People would probably drift towards using less explicit function names than form_id_submit().

The upsides would be some less complex processing code in areas of FormAPI that deal with callbacks, and a more explicit and readable connection between 'a button' and 'what happens when that button gets clicked' for those ramping up on the API. I think it would be a net gain, and I'll at least roll a version that works that way to see.

I don't, though, think we should hide buttons WITHOUT callbacks; for now, they serve to refresh a form, submitting it to itself, and there are valid cases where that would be useful. Those buttons, like #button elements today, would simply not fire off any dedicated code.

Attached is a patch that converts all of core to the 'callbacks required' system discussed above. I've done some rudimentary testing, but want to get it in front of other eyes for testing.

I think there's some value in looking at the same approach for validation -- we have a fair chunk of code that's dedicated to 'defaulting' these handlers, AND all of the funky '#base' code is made unnecessary if we make these things explicit. That's a separate issue, though.

here are a couple areas of the system that concerned me, because they're in less-cleanly-formapi'd portions of Drupal:

username/hostname mask filtering
system confirmation forms (this in particular, I think I broke. working more on it after I post this.)
poll voting
book orphan editing page
advanced node search

Testing in those areas is doubly helpful.

Re-rolled against the current HEAD. Confirm forms still broken.

Part of FAPI 3 in Drupal 6.

This issue was a new feature for Drupal 6, and won't be backported to Drupal 5.