I was reviewing drupal 6 modules searching for an standard for document form api callbacks, but it seems like there's not.

So, I think it could help a little to have one way to do it. Reviewing a little piece in d6 y d7 I got:

DRUPAL 6

I'll make copy here one examples of #submit (grep -nr "'#submit'" .):

$form['#submit'][] = 'system_admin_theme_submit';

/**
 * Process admin theme form submissions.
 */
function system_admin_theme_submit($form, &$form_state) {

This sound like a good way to do it, so using a little more descriptive text can do the work, like:
Process <form_id> form submissions
that would change the last one in "Process system_admin_theme_settings form submissions."

In the other hand, there are also some generic functions called in #submit like

$form['#submit'][] = 'drupal_clear_css_cache';

/**
 * Delete all cached CSS files.
 */
function drupal_clear_css_cache() {

and that kind of callback maybe does not make sense to be documented in the same way, so really not sure how to do it.

DRUPAL 7

In d7 those examples are:

$form['#submit'][] = 'system_theme_settings_submit';

/**
 * Process system_theme_settings form submissions.
 */
function system_theme_settings_submit($form, &$form_state) {

great, nothing to do here, and the other example

$form['#submit'][] = 'drupal_clear_css_cache';

/**
 * Delete all cached CSS files.
 */
function drupal_clear_css_cache() {

So, the same problem here.

I also see that updae module make a wrapper around to "solve" this:

function update_form_system_modules_alter(&$form, $form_state) {
  $form['#submit'][] = 'update_cache_clear_submit';
}

/**
 * Helper function for use as a form submit callback.
 */
function update_cache_clear_submit($form, &$form_state) {
  // Clear all update module caches.
  _update_cache_clear();
}

Any suggestions about this? or maybe there is some standard somewhere, or maybe it's not what we want?

Comments

jhodgdon’s picture

Specific submit/validate functions should include the name of the original form function in the header. E.g.:

/**
 * Submit function for form_abc_def().
 */
function form_abc_def_submit() {
}

Note that it needs parentheses after the name of the form, so that it will generate a link to the function that generates the form. Assuming that the function has the same name as the form; if not, something like this:

/**
  * Submit function for form_abc_def, which is generated by form_abc_pdq().
  */
function form_abc_def_submit() {
}
moshe weitzman’s picture

'process' already has a different meaning in fapi elements. i would go with form submit callback.

jhodgdon’s picture

Status: Active » Fixed

We now have a section documenting how to document form callbacks:
http://drupal.org/node/1354#forms

marvil07’s picture

great :-)

should I file a bug to make sure all core use that standard? or we should do it here?

For example:

/**
 * Helper function for use as a form submit callback.
 */
function update_cache_clear_submit($form, &$form_state) {
  // Clear all update module caches.
  _update_cache_clear();
}
jhodgdon’s picture

Separate issue please. This issue was about whether there was a standard.

marvil07’s picture

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.