Issue #2942627 by Mile23, joachim: calls to form state setRebuild() and setCached() need to be explained

Author: Mile23

form_api_example/src/Form/AjaxAddMore.php

@@ -74,7 +74,6 @@ public function buildForm(array $form, FormStateInterface $form_state) {
         ],
       ];
     }
-    $form_state->setCached(FALSE);
     $form['actions']['submit'] = [
       '#type' => 'submit',
       '#value' => $this->t('Submit'),
@@ -108,6 +107,9 @@ public function addOne(array &$form, FormStateInterface $form_state) {
     $name_field = $form_state->get('num_names');
     $add_button = $name_field + 1;
     $form_state->set('num_names', $add_button);
+    // Since our buildForm() method relies on the value of 'num_names' to
+    // generate 'name' form elements, we have to tell the form to rebuild. If we
+    // don't do this, the form builder will not call buildForm().
     $form_state->setRebuild();
   }
 
@@ -122,6 +124,9 @@ public function removeCallback(array &$form, FormStateInterface $form_state) {
       $remove_button = $name_field - 1;
       $form_state->set('num_names', $remove_button);
     }
+    // Since our buildForm() method relies on the value of 'num_names' to
+    // generate 'name' form elements, we have to tell the form to rebuild. If we
+    // don't do this, the form builder will not call buildForm().
     $form_state->setRebuild();
   }
 

form_api_example/src/Form/MultistepForm.php

@@ -129,6 +129,9 @@ public function fapiExampleMultistepFormNextSubmit(array &$form, FormStateInterf
         'birth_year' => $form_state->getValue('birth_year'),
       ])
       ->set('page_num', 2)
+      // Since we have logic in our buildForm() method, we have to tell the form
+      // builder to rebuild the form. Otherwise, even though we set 'page_num'
+      // to 2, the AJAX-rendered form will still show page 1.
       ->setRebuild(TRUE);
   }
 
@@ -187,6 +190,9 @@ public function fapiExamplePageTwoBack(array &$form, FormStateInterface $form_st
       // Restore values for the first step.
       ->setValues($form_state->get('page_values'))
       ->set('page_num', 1)
+      // Since we have logic in our buildForm() method, we have to tell the form
+      // builder to rebuild the form. Otherwise, even though we set 'page_num'
+      // to 1, the AJAX-rendered form will still show page 2.
       ->setRebuild(TRUE);
   }