#571086 by sun and merlinofchaos: Added a 'wrapper callback' that executes

before a form builder function, to facilitate common form elements. Clean-up
from form_builder changes from CTools patch. Has nice side-benefit of making
all form functions' signatures consistent.

2 files changed, 29 insertions, 17 deletions

diff --git a/includes/form.inc b/includes/form.inc
index 83e37c385..5ebd18b7c 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -95,7 +95,6 @@ function drupal_get_form($form_id) {
  *   An array which stores information about the form. This is passed as a
  *   reference so that the caller can use it to examine what the form changed
  *   when the form submission process is complete.
- *
  *   The following parameters may be set in $form_state to affect how the form
  *   is rendered:
  *   - args: An array of arguments to pass to the form builder.
@@ -117,6 +116,12 @@ function drupal_get_form($form_id) {
  *     times when a form is resubmitted internally and should be validated
  *     again. Setting this to TRUE will force that to happen. This is most
  *     likely to occur during AHAH or AJAX operations.
+ *   - wrapper_callback: Modules that wish to pre-populate certain forms with
+ *     common elements, such as back/next/save buttons in multi-step form
+ *     wizards, may define a form builder function name that returns a form
+ *     structure, which is passed on to the actual form builder function.
+ *     Such forms cannot use drupal_get_form() and need to prepare $form_state
+ *     on their own.
  * @return
  *   The rendered form or NULL, depending upon the $form_state flags that were set.
  */
@@ -464,10 +469,21 @@ function drupal_retrieve_form($form_id, &$form_state) {
     }
   }
 
- // We need to pass $form_state by reference in order for forms to modify it,
- // since call_user_func_array() requires that referenced variables be passed
- // explicitly.
-  $args = array_merge(array(&$form_state), $args);
+  // When the passed $form_state (not using drupal_get_form()) defines a
+  // 'wrapper_callback', then it requests to invoke a separate (wrapping) form
+  // builder function to pre-populate the $form array with form elements, which
+  // the actual form builder function ($callback) expects. This allows for
+  // pre-populating a form with common elements for certain forms, such as
+  // back/next/save buttons in multi-step form wizards.
+  // @see drupal_build_form()
+  $form = array();
+  if (isset($form_state['wrapper_callback']) && function_exists($form_state['wrapper_callback'])) {
+    $form = $form_state['wrapper_callback']($form, $form_state);
+  }
+  // We need to pass $form_state by reference in order for forms to modify it,
+  // since call_user_func_array() requires that referenced variables be passed
+  // explicitly.
+  $args = array_merge(array($form, &$form_state), $args);
 
   // If $callback was returned by a hook_forms() implementation, call it.
   // Otherwise, call the function named after the form id.
diff --git a/includes/locale.inc b/includes/locale.inc
index 8e803eb61..4962f2fd7 100644
--- a/includes/locale.inc
+++ b/includes/locale.inc
@@ -166,9 +166,8 @@ function locale_languages_add_screen() {
 /**
  * Predefined language setup form.
  */
-function locale_languages_predefined_form() {
+function locale_languages_predefined_form($form) {
   $predefined = _locale_prepare_predefined_list();
-  $form = array();
   $form['language list'] = array('#type' => 'fieldset',
     '#title' => t('Predefined language'),
     '#collapsible' => TRUE,
@@ -186,8 +185,7 @@ function locale_languages_predefined_form() {
 /**
  * Custom language addition form.
  */
-function locale_languages_custom_form() {
-  $form = array();
+function locale_languages_custom_form($form) {
   $form['custom language'] = array('#type' => 'fieldset',
     '#title' => t('Custom language'),
     '#collapsible' => TRUE,
@@ -210,9 +208,8 @@ function locale_languages_custom_form() {
  * @param $langcode
  *   Language code of the language to edit.
  */
-function locale_languages_edit_form(&$form_state, $langcode) {
+function locale_languages_edit_form($form, &$form_state, $langcode) {
   if ($language = db_query("SELECT * FROM {languages} WHERE language = :language", array(':language' => $langcode))->fetchObject()) {
-    $form = array();
     _locale_languages_common_controls($form, $language);
     $form['submit'] = array(
       '#type' => 'submit',
@@ -406,7 +403,7 @@ function locale_languages_edit_form_submit($form, &$form_state) {
 /**
  * User interface for the language deletion confirmation screen.
  */
-function locale_languages_delete_form(&$form_state, $langcode) {
+function locale_languages_delete_form($form, &$form_state, $langcode) {
 
   // Do not allow deletion of English locale.
   if ($langcode == 'en') {
@@ -698,7 +695,7 @@ function locale_translation_filter_form_submit($form, &$form_state) {
 /**
  * User interface for the translation import screen.
  */
-function locale_translate_import_form() {
+function locale_translate_import_form($form) {
   // Get all languages, except English
   drupal_static_reset('language_list');
   $names = locale_language_list('name');
@@ -716,7 +713,6 @@ function locale_translate_import_form() {
     $default = key($names);
   }
 
-  $form = array();
   $form['import'] = array('#type' => 'fieldset',
     '#title' => t('Import translation'),
   );
@@ -816,7 +812,7 @@ function locale_translate_export_screen() {
  * @param $names
  *   An associate array with localized language names
  */
-function locale_translate_export_po_form(&$form_state, $names) {
+function locale_translate_export_po_form($form, &$form_state, $names) {
   $form['export'] = array('#type' => 'fieldset',
     '#title' => t('Export translation'),
     '#collapsible' => TRUE,
@@ -881,7 +877,7 @@ function locale_translate_export_po_form_submit($form, &$form_state) {
 /**
  * User interface for string editing.
  */
-function locale_translate_edit_form(&$form_state, $lid) {
+function locale_translate_edit_form($form, &$form_state, $lid) {
   // Fetch source string, if possible.
   $source = db_query('SELECT source, context, textgroup, location FROM {locales_source} WHERE lid = :lid', array(':lid' => $lid))->fetchObject();
   if (!$source) {
@@ -1051,7 +1047,7 @@ function locale_translate_delete_page($lid) {
 /**
  * User interface for the string deletion confirmation screen.
  */
-function locale_translate_delete_form(&$form_state, $source) {
+function locale_translate_delete_form($form, &$form_state, $source) {
   $form['lid'] = array('#type' => 'value', '#value' => $source->lid);
   return confirm_form($form, t('Are you sure you want to delete the string "%source"?', array('%source' => $source->source)), 'admin/config/regional/translate/translate', t('Deleting the string will remove all translations of this string in all languages. This action cannot be undone.'), t('Delete'), t('Cancel'));
 }