Issue #2933259 by eojthebrave: Add some additional information to form_api_example #states demo

Author: eojthebrave

Diff for: form_api_example/src/Form/StateDemo.php

@@ -7,16 +7,17 @@
 /**
  * Implements the state demo form controller.
  *
- * This example demonstrates using the #state property to bind the visibility of
- * a form element to the value of another element in the form. In the example,
- * when the user checks the "Need Special Accommodation" checkbox, additional
- * form elements are made visible.
+ * This example demonstrates using the #states property to bind the visibility
+ * of a form element to the value of another element in the form. In the
+ * example, when the user checks the "Need Special Accommodation" checkbox,
+ * additional form elements are made visible.
  *
  * The submit handler for this form is implemented by the
  * \Drupal\form_api_example\Form\DemoBase class.
  *
  * @see \Drupal\Core\Form\FormBase
  * @see \Drupal\form_api_example\Form\DemoBase
+ * @see drupal_process_states()
  */
 class StateDemo extends DemoBase {
 
@@ -43,9 +44,22 @@ public function buildForm(array $form, FormStateInterface $form_state) {
       '#attributes' => [
         'class' => 'accommodation',
       ],
+      // #states is an associative array. Each key is the name of a state to
+      // apply to the element, such as 'visible'. Each value is another array,
+      // making a list of conditions that denote when the state should be
+      // applied. Every condition is a key/value pair, whose key is a jQuery
+      // selector that denotes another element on the page, and whose value is
+      // an array of conditions, which must bet met on in order for the state to
+      // be applied.
+      //
+      // For additional documentation on the #states property including a list
+      // of valid states and conditions see drupal_process_states().
       '#states' => [
+        // The state being affected is "invisible".
         'invisible' => [
-          'input[name="needs_accommodation"]' => ['checked' => FALSE],
+          // Drupal will only apply this state when the element that satisfies
+          // the selector input[name="needs_accommodation"] is un-checked.
+          ':input[name="needs_accommodation"]' => ['checked' => FALSE],
         ],
       ],
     ];

Diff for: form_api_example/tests/src/FunctionalJavascript/StateDemoTest.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Drupal\Tests\form_api_example\FunctionalJavascript;
+
+use Drupal\FunctionalJavascriptTests\JavascriptTestBase;
+use Drupal\Core\Url;
+
+/**
+ * @group form_api_example
+ *
+ * @ingroup form_api_example
+ */
+class StateDemoTest extends JavascriptTestBase {
+
+  /**
+   * Our module dependencies.
+   *
+   * @var string[]
+   */
+  static public $modules = ['form_api_example'];
+
+  /**
+   * Functional tests for the StateDemo example form.
+   */
+  public function testStateForm() {
+    // Visit form route.
+    $route = Url::fromRoute('form_api_example.state_demo');
+    $this->drupalGet($route);
+
+    // Get Mink stuff.
+    $page = $this->getSession()->getPage();
+
+    // Verify we can find the diet restrictions textfield, and that by default
+    // it is not visible.
+    $this->assertNotEmpty($checkbox = $page->find('css', 'input[name="diet"]'));
+    $this->assertFalse($checkbox->isVisible(), 'Diet restrictions field is not visible.');
+
+    // Check the needs special accommodation checkbox.
+    $page->checkField('needs_accommodation');
+
+    // Verify the textfield is visible now.
+    $this->assertTrue($checkbox->isVisible(), 'Diet restrictions field is visible.');
+  }
+
+}