Adding code comments. (#4289)

Author: dmundra

modules/data_dictionary_widget/data_dictionary_widget.module

@@ -102,7 +102,7 @@ function data_dictionary_widget_form_alter(&$form, &$form_state, $form_id) {
       }
     }
 
-    // If we are saving a data dictionary alter the submit.
+    // If we are saving a data dictionary alter the submit action.
     foreach (array_keys($form['actions']) as $action) {
       if ( isset($form['actions'][$action]['#type'])
         && $form['actions'][$action]['#type'] === 'submit'
@@ -112,11 +112,15 @@ function data_dictionary_widget_form_alter(&$form, &$form_state, $form_id) {
     }
 
     $form['#validate'][] = 'data_dictionary_widget_validate_unique_identifier';
+    // Check for existing dictionary and index fields.
     $current_dictionary_fields = !empty($form["field_json_metadata"]["widget"][0]["dictionary_fields"]["current_dictionary_fields"]) ? $form["field_json_metadata"]["widget"][0]["dictionary_fields"]["current_dictionary_fields"] : NULL;
     $current_index_fields = !empty($form["field_json_metadata"]["widget"][0]["indexes"]["current_index"]) ? $form["field_json_metadata"]["widget"][0]["indexes"]["current_index"] : NULL;
 
     // The form element render array prefers child keys to be stored as arrays with a #value property.
     if ($current_dictionary_fields) {
+      // Create an array to copy the formatted array structure.
+      $formatted_current_fields = [];
+
       foreach ($current_dictionary_fields as $key => $value) {
         $keys = array_keys($value);
         $formatted_current_fields[$key] = [];
@@ -142,14 +146,16 @@ function data_dictionary_widget_form_alter(&$form, &$form_state, $form_id) {
                 $fieldValue = ['#value' => $fieldValue];
               }
             }
-          } else {
-              // For non-'fields' keys, add '#value' key to the value
-              $value = ['#value' => $value];
+          }
+          else {
+            // For non-'fields' keys, add '#value' key to the value
+            $value = ['#value' => $value];
           }
         }
       }
 
-      $form["field_json_metadata"]["widget"][0]["indexes"]["current_index"] = $current_index_fields; 
+      // Note the current_index_fields was modified in memory instead of copying the array.
+      $form["field_json_metadata"]["widget"][0]["indexes"]["current_index"] = $current_index_fields;
     }
 
     // Set the default value of the identifier field to a randomly generated uuid.

modules/data_dictionary_widget/src/Fields/FieldCallbacks.php

@@ -101,6 +101,7 @@ public static function addSubformCallback(array &$form, FormStateInterface $form
     $trigger = $form_state->getTriggeringElement();
     $op = $trigger['#op'];
     $form_state->set('add_new_field', '');
+    // Get the current fields data.
     $current_dictionary_fields = $form["field_json_metadata"]["widget"][0]["dictionary_fields"]["data"]["#rows"];
     $current_index = $form["field_json_metadata"]["widget"][0]['indexes']["data"]["#rows"];
     $current_index_fields = $form["field_json_metadata"]["widget"][0]['indexes']["fields"]["data"]["#rows"] ?? [];

modules/data_dictionary_widget/src/Indexes/IndexFieldButtons.php

@@ -113,8 +113,12 @@ public static function editIndexButtons($indexKey) {
   public static function submitIndexFieldButton($location, $indexKey) {
     $callbackClass = $location == 'edit' ? 'indexEditSubformCallback' : 'indexAddSubformCallback';
     $op = !empty($indexKey) ? 'update_' . $indexKey : 'add_index_field';
+    // @TODO fix the 'Add ' to drop the space, this will need the test to be
+    // updated as well.
     $value = $location == 'edit' ? 'Save' : 'Add ';
-    $function = $location == 'edit' ? 'subIndexFormAjax' : 'subIndexFormAjax';
+    // Index fields cannot be edited once submitted so we use the same function
+    // for both add and edit.
+    $function = 'subIndexFormAjax';
     $edit_index_button = [
       '#type' => 'submit',
       '#value' => $value,

modules/data_dictionary_widget/src/Indexes/IndexFieldCallbacks.php

@@ -13,8 +13,10 @@ class IndexFieldCallbacks {
    * Submit callback for the Index Add button.
    */
   public static function indexAddSubformCallback(array &$form, FormStateInterface $form_state) {
+    // Get the button's trigger value.
     $trigger = $form_state->getTriggeringElement();
     $op = $trigger['#op'];
+    // Get the current fields data.
     $current_dictionary_fields = $form["field_json_metadata"]["widget"][0]["dictionary_fields"]["data"]["#rows"] ?? [];
     $current_index = $form["field_json_metadata"]["widget"][0]['indexes']["data"]["#rows"] ?? [];
     $current_index_fields = $form["field_json_metadata"]["widget"][0]['indexes']["fields"]["data"]["#rows"] ?? [];
@@ -23,169 +25,252 @@ public static function indexAddSubformCallback(array &$form, FormStateInterface
       $form_state->set('current_index_fields', $current_index_fields);
     }
 
+    // If cancelling index field.
     if ($op === 'cancel_index_field') {
+      // Set the display to show the current index fields values.
       $form_state->set('cancel_index_field', TRUE);
+      // Hide the field collection.
       $form_state->set('add_new_index_field', '');
     }
 
+    // If adding new index field, this is triggered when you click the button to
+    // 'Add'
     if ($op === 'add_new_index_field') {
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('add_index_field', '');
+      // Get the form fields for adding new index fields.
       $add_index_fields = IndexFieldAddCreation::addIndexFields($current_index_fields);
+      // Set the fields in the field collection.
       $form_state->set('add_new_index_field', $add_index_fields);
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('index_added', FALSE);
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('adding_new_index_fields', TRUE);
     }
 
+    // If saving new index field.
     if ($op === 'add_index_field') {
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('add_new_index_field', '');
+      // Get and save the entered values.
       $form_state->set('new_index_fields', $form_state->getUserInput());
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('add', TRUE);
+      // Set the display to show the entered values.
       $form_state->set('cancel_index_field', FALSE);
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('adding_new_index_fields', FALSE);
     }
 
+    // Let's retain the fields that are already stored on the form,
+    // but aren't currently being modified.
     $form_state->set('current_dictionary_fields', $current_dictionary_fields);
     $form_state->set('current_index', $current_index);
     $form_state->set('current_index_fields', $current_index_fields);
+    // Let's rebuild the form.
     $form_state->setRebuild();
   }
 
   /**
    * Submit callback for the Index Add button.
    */
   public static function indexAddCallback(array &$form, FormStateInterface $form_state) {
+    // Get the button's trigger value.
     $trigger = $form_state->getTriggeringElement();
     $op = $trigger['#op'];
+    // Get the current fields data.
     $current_dictionary_fields = $form["field_json_metadata"]["widget"][0]["dictionary_fields"]["data"]["#rows"];
+    $current_index = $form["field_json_metadata"]["widget"][0]["indexes"]["data"]["#rows"];
+    $current_index_fields = $form["field_json_metadata"]["widget"][0]['indexes']["fields"]["data"]["#rows"] ?? NULL;
+    // Initialize the various field storage values.
     $form_state->set('add_new_index_field', '');
     $form_state->set('new_index_fields', '');
     $form_state->set('add_new_index', '');
+    // @TODO not being used so maybe removable or update the comment.
     $form_state->set('adding_new_index_fields', FALSE);
-    $current_index = $form["field_json_metadata"]["widget"][0]["indexes"]["data"]["#rows"];
-    $current_index_fields = $form["field_json_metadata"]["widget"][0]['indexes']["fields"]["data"]["#rows"] ?? NULL;
 
     if ($current_index) {
       $form_state->set('current_index', $current_index);
     }
 
+    // If cancelling index.
     if ($op === 'cancel_index') {
+      // Set the display to show the current index values.
       $form_state->set('cancel_index', TRUE);
     }
 
+    // If adding new index, this is triggered when you click the button to
+    // 'Add index'
     if ($op === 'add_new_index') {
+      // Get the form fields for adding new index.
       $add_new_index = IndexFieldAddCreation::addIndex();
+      // Set the new_index values to empty.
       $form_state->set('new_index', '');
+      // Set the fields in the field collection.
       $form_state->set('add_new_index', $add_new_index);
     }
 
+    // If saving new index.
     if ($op === 'add_index') {
+      // Empty the fields in the field collection.
       $form_state->set('add_new_index', '');
+      // Get and save the entered values.
       $form_state->set('new_index', $form_state->getUserInput());
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('add', TRUE);
+      // @TODO not being used so maybe removable or update the comment.
       $form_state->set('index_added', TRUE);
+      // Set the display to show the entered values.
       $form_state->set('cancel_index', FALSE);
     }
 
+    // Let's retain the fields that are already stored on the form,
+    // but aren't currently being modified.
     $form_state->set('current_dictionary_fields', $current_dictionary_fields);
     $form_state->set('current_index', $current_index);
     $form_state->set('current_index_fields', $current_index_fields);
+    // Let's rebuild the form.
     $form_state->setRebuild();
   }
 
   /**
    * Submit callback for the Index Field Edit button.
    */
   public static function indexEditSubformCallback(array &$form, FormStateInterface $form_state) {
+    // Get the button's trigger value.
     $trigger = $form_state->getTriggeringElement();
+    $op = $trigger['#op'];
+    // The location of the index field is stored in the operation key.
+    // We split the key to get the index field location.
+    $op_index = explode('_', $trigger['#op']);
+    // Get the current fields data.
     $current_index_fields = $form["field_json_metadata"]["widget"][0]["indexes"]["fields"]["data"]["#rows"];
     $current_dictionary_fields = $form["field_json_metadata"]["widget"][0]["dictionary_fields"]["data"]["#rows"];
-    $op = $trigger['#op'];
-    $op_index = explode("_", $trigger['#op']);
     $currently_modifying_index_fields = $form_state->get('index_fields_being_modified') != NULL ? $form_state->get('index_fields_being_modified') : [];
     $currently_modifying = $form_state->get('dictionary_fields_being_modified') != NULL ? $form_state->get('dictionary_fields_being_modified') : [];
 
+    // If the op (trigger) contains abort,
+    // We're canceling the field we're currently modifying so unset it.
     if (str_contains($op, 'abort')) {
       unset($currently_modifying_index_fields[$op_index[4]]);
     }
 
+    // If the op (trigger) contains delete,
+    // We're deleting the field we're editing so...
     if (str_contains($op, 'delete')) {
+      // Unset it from being currently modified.
       unset($currently_modifying_index_fields[$op_index[4]]);
+      // Remove the respective field/data from the form.
       unset($current_index_fields[$op_index[4]]);
     }
 
+    // If the op (trigger) contains update,
+    // We're saving the field we're editing so...
     if (str_contains($op, 'update')) {
+      // Get the entered data.
       $update_values = $form_state->getUserInput();
+      // Unset the respective currently modifying field.
       unset($currently_modifying_index_fields[$op_index[4]]);
+      // Unset the respective field/data from the form.
       unset($current_index_fields[$op_index[4]]);
+      // Update the respective current field data with our new input data.
       $current_index_fields[$op_index[4]] = IndexFieldValues::updateIndexFieldValues($op_index[4], $update_values, $current_index_fields);
+      // Sort the current index fields data.
       ksort($current_index_fields);
-
-    }
-
-    if (str_contains($op, 'edit_index_key')) {
-      $currently_modifying_index_fields[$op_index[4]] = $current_index_fields[$op_index[4]];
     }
 
+    // If the op (trigger) contains edit
+    // We're editing a specific field so...
     if (str_contains($op, 'edit_index_field')) {
+      // Set the field we're modifying to that field.
       $currently_modifying_index_fields[$op_index[4]] = $current_index_fields[$op_index[4]];
     }
 
+    // Let's retain the fields that are being modified.
     $form_state->set('dictionary_fields_being_modified', $currently_modifying);
     $form_state->set('index_fields_being_modified', $currently_modifying_index_fields);
+    // Let's retain the fields that are already stored on the form,
+    // but aren't currently being modified.
     $form_state->set('current_index_fields', $current_index_fields);
     $form_state->set('current_dictionary_fields', $current_dictionary_fields);
+    // Let's rebuild the form.
     $form_state->setRebuild();
   }
 
   /**
    * Submit callback for the Index Edit button.
    */
   public static function indexEditCallback(array &$form, FormStateInterface $form_state) {
+    // Get the button's trigger value.
     $trigger = $form_state->getTriggeringElement();
+    $op = $trigger['#op'];
+    // The location of the index is stored in the operation key.
+    // We split the key to get the index location.
+    $op_index = explode('_', $trigger['#op']);
+    // Get the current fields data.
     $current_index_fields = $form['field_json_metadata']['widget'][0]['indexes']['fields']['data']['#rows'] ?? [];
     $current_index = $form['field_json_metadata']['widget'][0]['indexes']['data']['#rows'] ?? [];
     $current_dictionary_fields = $form['field_json_metadata']['widget'][0]['dictionary_fields']['data']['#rows'] ?? [];
-    $op = $trigger['#op'];
-    $op_index = explode('_', $trigger['#op']);
     $currently_modifying_index_fields = $form_state->get('index_fields_being_modified') != NULL ? $form_state->get('index_fields_being_modified') : [];
     $currently_modifying_index = $form_state->get('index_being_modified') != NULL ? $form_state->get('index_being_modified') : [];
     $currently_modifying_dictionary_fields = $form_state->get('dictionary_fields_being_modified') != NULL ? $form_state->get('dictionary_fields_being_modified') : [];
 
+    // If the op (trigger) contains abort,
+    // We're canceling the index we're currently modifying so unset it.
     if (str_contains($op, 'abort_index_key')) {
       unset($currently_modifying_index[$op_index[3]]);
     }
-
+    // We're canceling the index field we're currently modifying so unset it.
     if (str_contains($op, 'abort_index_field_key')) {
       unset($currently_modifying_index_fields[$op_index[4]]);
     }
 
+    // If the op (trigger) contains delete,
+    // We're deleting the index we're editing so...
     if (str_contains($op, 'delete_index_key')) {
+      // Unset it from being currently modified.
       unset($currently_modifying_index[$op_index[3]]);
+      // Remove the respective field/data from the form.
       unset($current_index[$op_index[3]]);
     }
-
+    // We're deleting the index field we're editing so...
     if (str_contains($op, 'delete_index_field_key')) {
+      // Unset it from being currently modified.
       unset($currently_modifying_index_fields[$op_index[4]]);
+      // Remove the respective field/data from the form.
       unset($current_index_fields[$op_index[4]]);
     }
 
+    // If the op (trigger) contains update,
+    // We're saving the field we're editing so...
     if (str_contains($op, 'update')) {
+      // Get the entered data.
       $update_values = $form_state->getUserInput();
+      // Update the respective current field data with our new input data.
       $current_index[$op_index[3]] = IndexFieldValues::updateIndexValues($op_index[3], $update_values, $current_index);
+      // Unset the respective field/data from the form.
       unset($currently_modifying_index[$op_index[3]]);
+      // Sort the current index data.
       ksort($current_index);
     }
 
+    // If the op (trigger) contains edit
+    // We're editing a specific field so...
     if (str_contains($op, 'edit')) {
+      // Set the field we're modifying to that field.
       $currently_modifying_index[$op_index[3]] = $current_index[$op_index[3]];
     }
 
+    // Let's retain the fields that are being modified.
     $form_state->set('dictionary_fields_being_modified', $currently_modifying_dictionary_fields);
     $form_state->set('index_fields_being_modified', $currently_modifying_index_fields);
     $form_state->set('index_being_modified', $currently_modifying_index);
+    // Let's retain the fields that are already stored on the form,
+    // but aren't currently being modified.
     $form_state->set('current_index_fields', $current_index_fields);
     $form_state->set('current_index', $current_index);
     $form_state->set('current_dictionary_fields', $current_dictionary_fields);
+    // Let's rebuild the form.
     $form_state->setRebuild();
   }
 
@@ -220,15 +305,15 @@ public static function indexFormAjax(array &$form, FormStateInterface $form_stat
   }
 
   /**
-   * Ajax callback to return index fields fieldset with Add Field button.
+   * Ajax callback to return index fields fieldset with 'Add Field' button.
    */
   public static function subIndexFormFieldAjax(array &$form, FormStateInterface $form_state) {
     return $form["field_json_metadata"]["widget"][0]["indexes"]["field_collection"]["group"]["index"]["fields"];
   }
 
   /**
-   * Ajax callback to return index fields fieldset with existing fields and Add
-   * Field button.
+   * Ajax callback to return index fields fieldset with existing fields and 'Add
+   * Field' button.
    */
   public static function subIndexFormExistingFieldAjax(array &$form, FormStateInterface $form_state) {
     $form["field_json_metadata"]["widget"][0]["indexes"]["field_collection"]["group"]["index"]["fields"]["add_row_button"]['#access'] = TRUE;

modules/data_dictionary_widget/src/Indexes/IndexFieldCreation.php

@@ -41,7 +41,7 @@ public static function createGeneralIndex($element, $current_indexes) {
   }
 
   /**
-   * Create data index data rows.
+   * Create data index fields data rows.
    */
   public static function createIndexFieldsDataRows($index_field_values, $current_index_fields, $index_fields_data_results, $form_state) {
     if ($index_field_values) {

modules/data_dictionary_widget/src/Indexes/IndexFieldEditCreation.php

@@ -10,8 +10,9 @@ class IndexFieldEditCreation {
   /**
    * Create edit index fields.
    */
-  public static function editIndexFields($indexKey, $current_index_fields, $index_fields_being_modified) {
-    $id = $current_index_fields ? "field-json-metadata-index-fields" : "field-json-metadata-index-fields-new";
+  public static function editIndexFields($indexKey, $current_index_fields) {
+    $id = $current_index_fields ? 'field-json-metadata-index-fields' : 'field-json-metadata-index-fields-new';
+    // We split the key to get the index field location.
     $indexKeyExplode = explode("_", $indexKey);
     $edit_index_fields['name'] = [
       '#name' => 'field_json_metadata[0][indexes][fields][edit_index_fields][' . $indexKeyExplode[3] . '][name]',
@@ -36,7 +37,7 @@ public static function editIndexFields($indexKey, $current_index_fields, $index_
   /**
    * Create edit index.
    */
-  public static function editIndex($indexKey, $current_index, $index_being_modified, $form_state) {
+  public static function editIndex($indexKey, $current_index, $form_state) {
     $id = $current_index ? "field-json-metadata-index-new" : "field-json-metadata-index";
     $indexKeyExplode = explode("_", $indexKey);