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
Comment #1
jhodgdonSpecific submit/validate functions should include the name of the original form function in the header. E.g.:
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:
Comment #2
moshe weitzman commented'process' already has a different meaning in fapi elements. i would go with form submit callback.
Comment #3
jhodgdonWe now have a section documenting how to document form callbacks:
http://drupal.org/node/1354#forms
Comment #4
marvil07 commentedgreat :-)
should I file a bug to make sure all core use that standard? or we should do it here?
For example:
Comment #5
jhodgdonSeparate issue please. This issue was about whether there was a standard.
Comment #6
marvil07 commentedok, issue created at #758546: Use standard to document form callbacks