Drupal form submit, form after_build

Question

What is the difference between $form['#submit'] and $form['#after_build']?

Answer 1

The api docs lay this out fairly well. $form['#submit'] will add an array of submit handlers to your form: ie when someone clicks the "Submit" button the function in the array will be called. These will be called after submission.

You generally would want to use this property when you are calling hook_form_alter() to add another submit function on to a form that you didn't build yourself, as if you create the form yourself in code, you also create the default submit handler. Here are the FAPI docs on #submit.

$form['#after_build'] is similar in that it takes an array of of functions to call, but they will be called after the form is built for display. This can be used if you have a default or existing value in a form element, and want to check the status of something with that value before submission. See the FAPI docs for a good example of checking the status of something before submission, after the form is built to be displayed.

So in summary, $form['#submit'] functions will be called upon submission, and $form['#after_build'] functions will be called upon display of the form.