From 206d4405c1082e768641d31738c6f554641b39d7 Mon Sep 17 00:00:00 2001
From: Arlen Johnson <arlen@sphericalcowgroup.com>
Date: Tue, 13 Jun 2023 14:27:28 -0400
Subject: [PATCH] Use named parameters to simplify the FieldHelper::control()
 function (CFM-269) (#92)

---
 app/src/View/Helper/FieldHelper.php           | 85 ++++++++++---------
 app/templates/ApiUsers/fields.inc             |  9 +-
 .../ExternalIdentityRoles/fields.inc          |  6 +-
 app/templates/Jobs/fields.inc                 | 57 ++++++-------
 app/templates/PersonRoles/fields.inc          |  2 +-
 5 files changed, 79 insertions(+), 80 deletions(-)

diff --git a/app/src/View/Helper/FieldHelper.php b/app/src/View/Helper/FieldHelper.php
index 437e17575..2329855c7 100644
--- a/app/src/View/Helper/FieldHelper.php
+++ b/app/src/View/Helper/FieldHelper.php
@@ -78,18 +78,24 @@ public function banner(string $info): string {
    * @param  string  $fieldName   Form field
    * @param  array   $options     FormHelper control options
    * @param  string  $labelText   Label text (fieldName language key used by default)
-   * @param  array   $config      Custom FormHelper configuration options
    * @param  string  $ctrlCode    Control code passed in from wrapper functions
    * @param  string  $cssClass    Start li css class passed in from wrapper functions
+   * @param  string  $beforeField Markup to be placed before/above the field
+   * @param  string  $afterField  Markup to be placed after/below the field
+   * @param  string  $prefix      Field prefix - used for API Usernames
+   * @param  bool    $labelIsTextOnly For fields that should not include <label> markup
    * @return string  HTML for control
    */
   
   public function control(string $fieldName,
-                          array  $options=[],
-                          string $labelText=null,
-                          array  $config=[],
-                          string $ctrlCode=null,
-                          string $cssClass=''): string {
+                          array  $options = [],
+                          string $labelText = null,
+                          string $ctrlCode = null,
+                          string $cssClass = '',
+                          string $beforeField = '',
+                          string $afterField = '',
+                          string $prefix = '',
+                          bool   $labelIsTextOnly = false): string {
     $coptions = $options;
     $coptions['label'] = false;
     $coptions['readonly'] = 
@@ -107,18 +113,11 @@ public function control(string $fieldName,
     $fieldMap = $this->getView()->get('vv_field_types');
     $fieldType = $fieldMap[$fieldName];
     
-    // Collect any supplemental markup and/or JavaScript to pass along for field construction.
-    // Suppliment is an array: supplement['beforeField' => 'string', 'afterField' => 'string'].
-    $fieldSupplement = !empty($config['supplement']) ? $config['supplement'] : [];
-  
-    // For special fields that should not include <label> markup, allow fields to make the label text only
-    $labelIsTextOnly = !empty($config['labelIsTextOnly']) ? $config['labelIsTextOnly'] : false;
-
     // Remove prefix from field value
-    if(isset($config['prefix'], $this->getView()->get('vv_obj')->$fieldName)) {
+    if(!empty($prefix) && !empty($this->getView()->get('vv_obj')->$fieldName)) {
       $vv_obj = $this->getView()->get('vv_obj');
       $fieldValue = $vv_obj->$fieldName;
-      $fieldValueTemp = str_replace($config['prefix'], '', $fieldValue);
+      $fieldValueTemp = str_replace($prefix, '', $fieldValue);
       $vv_obj->$fieldName = $fieldValueTemp;
       $this->getView()->set('vv_obj', $vv_obj);
     }
@@ -174,9 +173,9 @@ public function control(string $fieldName,
     
     return $this->startLine($liClass)
            . $this->formNameDiv($fieldName, $labelText, $fieldType, $labelIsTextOnly)
-           . ( !empty($config['prefix']) ?
-                 $this->formInfoWithPrefixDiv($controlCode, $config['prefix'], $fieldSupplement) :
-                 $this->formInfoDiv($controlCode, $fieldSupplement) )
+           . ( !empty($prefix) ?
+                 $this->formInfoWithPrefixDiv($controlCode, $prefix, $beforeField, $afterField) :
+                 $this->formInfoDiv($controlCode, $beforeField, $afterField) )
            . $this->endLine();
   }
   
@@ -261,7 +260,7 @@ public function dateControl(string $fieldName, string $dateType=DateTypeEnum::St
     $liClass = "fields-datepicker";
     
     // Pass everything to the generic control() function
-    return $this->control($fieldName, $coptions, '', [], $controlCode, $liClass);
+    return $this->control($fieldName, $coptions, ctrlCode: $controlCode, cssClass: $liClass);
   }
   
   /**
@@ -293,18 +292,21 @@ protected function endLine(): string {
    *
    * @since  COmanage Registry v5.0.0
    * @param  string  $content    Content HTML
-   * @param  string  $supplement Supplemental markup to place before and/or after the field control 
+   * @param  string  $beforeField Markup to be placed before/above the field
+   * @param  string  $afterField  Markup to be placed after/below the field
    * @return string              Form Info HTML
    */
   
-  protected function formInfoDiv(string $content, array $supplement): string {
+  protected function formInfoDiv(string $content, 
+                                 string $beforeField = '', 
+                                 string $afterField = ''): string {
     $div  = '<div class="field-info">' . PHP_EOL;
-    if(!empty($supplement['beforeField'])) {
-      $div .= $supplement['beforeField'] . PHP_EOL;
+    if(!empty($beforeField)) {
+      $div .= $beforeField . PHP_EOL;
     }
     $div .= $content . PHP_EOL;
-    if(!empty($supplement['afterField'])) {
-      $div .= $supplement['afterField'] . PHP_EOL;  
+    if(!empty($afterField)) {
+      $div .= $afterField . PHP_EOL;  
     }
     $div .= '</div>' . PHP_EOL;
     
@@ -315,16 +317,20 @@ protected function formInfoDiv(string $content, array $supplement): string {
    * Generate a form info (control, value) box with a non editable prefix.
    *
    * @since  COmanage Registry v5.0.0
-   * @param  string  $content    Content HTML
-   * @param  string  $prefix     Prefix value
-   * @param  string  $supplement Supplemental markup to place before and/or after the field control
-   * @return string              Form Info HTML
+   * @param  string  $content     Content HTML
+   * @param  string  $prefix      Prefix value
+   * @param  string  $beforeField Markup to be placed before/above the field
+   * @param  string  $afterField  Markup to be placed after/below the field
+   * @return string               Form Info HTML
    */
 
-  protected function formInfoWithPrefixDiv(string $context, string $prefix, array $supplement): string {
+  protected function formInfoWithPrefixDiv(string $context, 
+                                           string $prefix, 
+                                           string $beforeField = '', 
+                                           string $afterField = ''): string {
     $div  = '<div class="field-info">' . PHP_EOL;
-    if(!empty($supplement['beforeField'])) {
-      $div .= $supplement['beforeField'] . PHP_EOL;
+    if(!empty($beforeField)) {
+      $div .= $beforeField . PHP_EOL;
     }
     $div .= '<div class="input-group mb-3">' . PHP_EOL;
     $div .= '<div class="input-group-prepend">' . PHP_EOL;
@@ -332,8 +338,8 @@ protected function formInfoWithPrefixDiv(string $context, string $prefix, array
     $div .= '</div>' . PHP_EOL;
     $div .= $context;
     $div .= '</div>';
-    if(!empty($supplement['afterField'])) {
-      $div .= $supplement['afterField'] . PHP_EOL;
+    if(!empty($afterField)) {
+      $div .= $afterField . PHP_EOL;
     }
     $div .= '</div>';
 
@@ -467,15 +473,15 @@ protected function formNameDiv(string $fieldName, string $labelText=null, string
    * @param  string  $status    Status text
    * @param  array   $link      Link information, including 'url', 'label', 'class', 'confirm'
    * @param  string  $labelText Label text (fieldName language key used by default)
-   * @param  array   $config    Custom FormHelper configuration options
+   * @param  boolean $labelIsTextOnly true if <label> wrapper should not be included in the markup
    * @return string
    */
   
   public function statusControl(string $fieldName, 
                                 string $status, 
-                                array $link=[], 
-                                string $labelText=null,
-                                array $config=[]): string {
+                                array  $link=[], 
+                                string $labelText = null,
+                                bool   $labelIsTextOnly = false): string {
     $linkHtml = $status;
     
     if($link) {
@@ -500,9 +506,6 @@ public function statusControl(string $fieldName,
         );
       }
     }
-  
-    // For special fields that should not include <label> markup, allow fields to make the label text only
-    $labelIsTextOnly = !empty($config['labelIsTextOnly']) ? $config['labelIsTextOnly'] : false;
      
     return $this->startLine()
            . $this->formNameDiv($fieldName, $labelText, 'string', $labelIsTextOnly)
diff --git a/app/templates/ApiUsers/fields.inc b/app/templates/ApiUsers/fields.inc
index 065255c24..f2c9682cc 100644
--- a/app/templates/ApiUsers/fields.inc
+++ b/app/templates/ApiUsers/fields.inc
@@ -32,11 +32,11 @@ if($vv_action == 'add' || $vv_action == 'edit') {
   }
   
   // AR-ApiUser-3 For namespacing purposes, API Users are named with a prefix consisting of the string "co_#.".
-  print $this->Field->control('username', [], null, ['prefix' => "co_" . $vv_cur_co->id .'.']);
+  print $this->Field->control('username', prefix: 'co_' . $vv_cur_co->id . '.');
   
   // We link to the "Generate" button on edit only
   $generateLink = [];
-  $config = [];
+  $labelIsTextOnly = false;
   
   if(!empty($vv_obj->id)) {
     $generateLink = [
@@ -50,14 +50,13 @@ if($vv_action == 'add' || $vv_action == 'edit') {
      'confirm' => __d('operation', 'api.key.generate.confirm')
     ];
     
-    $config = ['labelIsTextOnly' => true];
+    $labelIsTextOnly = true;
   }
   
   print $this->Field->statusControl('api_key',
                                     !empty($vv_obj->api_key) ? __d('enumeration', 'SetBooleanEnum.1') : __d('enumeration', 'SetBooleanEnum.0'),
                                     $generateLink,
-                                    null,
-                                    $config);
+                                    labelIsTextOnly: $labelIsTextOnly);
   
   print $this->Field->control('status', ['empty' => false]);
   
diff --git a/app/templates/ExternalIdentityRoles/fields.inc b/app/templates/ExternalIdentityRoles/fields.inc
index e0d159178..d1301089d 100644
--- a/app/templates/ExternalIdentityRoles/fields.inc
+++ b/app/templates/ExternalIdentityRoles/fields.inc
@@ -27,7 +27,7 @@
 
 // This view does not currently support read-only
 if($vv_action == 'add' || $vv_action == 'edit') {
-  print $this->Field->control('affiliation_type_id', [], __d('field', 'affiliation'));
+  print $this->Field->control('affiliation_type_id', labelText: __d('field', 'affiliation'));
   
   print $this->Field->control('status', ['empty' => false]);
   
@@ -40,9 +40,9 @@ if($vv_action == 'add' || $vv_action == 'edit') {
   print $this->Field->control('department');
   
 // XXX need to clarify this is an _identifier_ not an actual Person FK
-  print $this->Field->control('sponsor_identifier', [], __d('field', 'sponsor'));
+  print $this->Field->control('sponsor_identifier', labelText: __d('field', 'sponsor'));
   
-  print $this->Field->control('manager_identifier', [], __d('field', 'manager'));
+  print $this->Field->control('manager_identifier', labelText: __d('field', 'manager'));
   
   print $this->Field->dateControl('valid_from');
   
diff --git a/app/templates/Jobs/fields.inc b/app/templates/Jobs/fields.inc
index 71c3eee08..238a9da85 100644
--- a/app/templates/Jobs/fields.inc
+++ b/app/templates/Jobs/fields.inc
@@ -38,36 +38,33 @@ if($vv_action == 'view') {
     );
   }
   
-  $fieldSupplement = 
-    [
-      'beforeField' => '
-        <div class="field-suppliment">
-          <div class="form-check">
-            <input class="form-check-input" type="checkbox" value="" id="format-toggle">
-            <label class="form-check-label" for="format-toggle">' .
-              __d('field','format')
-            . '</label>
-          </div>
-        </div>
-      ',
-      'afterField' => '
-        <script>
-          parametersValue = $("#parameters").val();
-          parametersJSON = JSON.parse(parametersValue);
-          $("#format-toggle").click(function() {
-            if($(this).is(":checked")) {         
-              $("#parameters").val(JSON.stringify(parametersJSON, null, 4));
-              paramsHeight = Object.keys(parametersJSON).length + 6 + "em";
-              $("#parameters").css("height",paramsHeight);
-            } else {
-              $("#parameters").val(parametersValue);
-              $("#parameters").css("height","4em");
-            }
-          });
-        </script>
-      '
-    ];
-  print $this->Field->control('parameters', [], null, ['supplement' => $fieldSupplement]);
+  $beforeField = '
+    <div class="field-suppliment">
+      <div class="form-check">
+        <input class="form-check-input" type="checkbox" value="" id="format-toggle">
+        <label class="form-check-label" for="format-toggle">' .
+          __d('field','format')
+        . '</label>
+      </div>
+    </div>
+  ';
+  $afterField = '
+    <script>
+      parametersValue = $("#parameters").val();
+      parametersJSON = JSON.parse(parametersValue);
+      $("#format-toggle").click(function() {
+        if($(this).is(":checked")) {         
+          $("#parameters").val(JSON.stringify(parametersJSON, null, 4));
+          paramsHeight = Object.keys(parametersJSON).length + 6 + "em";
+          $("#parameters").css("height",paramsHeight);
+        } else {
+          $("#parameters").val(parametersValue);
+          $("#parameters").css("height","4em");
+        }
+      });
+    </script>
+  ';
+  print $this->Field->control('parameters', beforeField: $beforeField, afterField: $afterField);
 
   print $this->Field->control('register_time');
 
diff --git a/app/templates/PersonRoles/fields.inc b/app/templates/PersonRoles/fields.inc
index 749952f73..c8fa75cef 100644
--- a/app/templates/PersonRoles/fields.inc
+++ b/app/templates/PersonRoles/fields.inc
@@ -29,7 +29,7 @@
 if($vv_action == 'add' || $vv_action == 'edit') {
   print $this->Field->control('cou_id');
   
-  print $this->Field->control('affiliation_type_id', [], __d('field', 'affiliation'));
+  print $this->Field->control('affiliation_type_id', labelText: __d('field', 'affiliation'));
   
   print $this->Field->control('status', ['empty' => false]);