From ec9e7df3ba56ea80f0e5184e3354de946abc3c60 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 29 Oct 2019 15:31:06 -0700
Subject: [PATCH] ArrayHtml - Support comments

Before
------

HTML comments appear in the array as NULL values

After
-----

HTML comments appear in the array as `['#comment' => '...']`

Technical Notes
---------------

* Considered using `['#tag' => 'comment', '#children' => '...'], but this is ambiguous when you
  have a node/tag named '<comment>'
* Considered using `['#tag' => 'comment', '#children' => '...'], but it's needlessly difficult to
  extract the comment text from under `'#children'`.
---
 ext/afform/core/CRM/Afform/ArrayHtml.php      | 11 ++++++-
 .../mock/tests/phpunit/api/v4/AfformTest.php  |  2 +-
 .../api/v4/formatExamples/comments.php        | 31 +++++++++++++++++++
 3 files changed, 42 insertions(+), 2 deletions(-)
 create mode 100644 ext/afform/mock/tests/phpunit/api/v4/formatExamples/comments.php

diff --git a/ext/afform/core/CRM/Afform/ArrayHtml.php b/ext/afform/core/CRM/Afform/ArrayHtml.php
index a3086c514a..98204aa65f 100644
--- a/ext/afform/core/CRM/Afform/ArrayHtml.php
+++ b/ext/afform/core/CRM/Afform/ArrayHtml.php
@@ -59,6 +59,14 @@ class CRM_Afform_ArrayHtml {
       return '';
     }
 
+    if (isset($array['#comment'])) {
+      if (strpos($array['#comment'], '-->')) {
+        Civi::log()->warning('Afform: Cannot store comment with text "-->". Munging.');
+        $array['#comment'] = str_replace('-->', '-- >', $array['#comment']);
+      }
+      return sprintf('<!--%s-->', $array['#comment']);
+    }
+
     $tag = empty($array['#tag']) ? self::DEFAULT_TAG : $array['#tag'];
     unset($array['#tag']);
     $children = empty($array['#children']) ? [] : $array['#children'];
@@ -153,7 +161,8 @@ class CRM_Afform_ArrayHtml {
       return $node->textContent;
     }
     elseif ($node instanceof DOMComment) {
-      // FIXME: How to preserve comments? For the moment, discarding them.
+      $arr = ['#comment' => $node->nodeValue];
+      return $arr;
     }
     else {
       throw new \RuntimeException("Unrecognized DOM node");
diff --git a/ext/afform/mock/tests/phpunit/api/v4/AfformTest.php b/ext/afform/mock/tests/phpunit/api/v4/AfformTest.php
index 606ac9c29a..f63272b6fe 100644
--- a/ext/afform/mock/tests/phpunit/api/v4/AfformTest.php
+++ b/ext/afform/mock/tests/phpunit/api/v4/AfformTest.php
@@ -65,7 +65,7 @@ class api_v4_AfformTest extends api_v4_AfformTestCase {
   public function getFormatExamples() {
     $es = [];
 
-    foreach (['empty', 'string', 'apple', 'banana', 'cherry'] as $exampleName) {
+    foreach (['empty', 'string', 'comments', 'apple', 'banana', 'cherry'] as $exampleName) {
       $exampleFile = '/formatExamples/' . $exampleName . '.php';
       $example = require __DIR__ . $exampleFile;
       $formats = ['html', 'shallow', 'deep'];
diff --git a/ext/afform/mock/tests/phpunit/api/v4/formatExamples/comments.php b/ext/afform/mock/tests/phpunit/api/v4/formatExamples/comments.php
new file mode 100644
index 0000000000..248cffddb3
--- /dev/null
+++ b/ext/afform/mock/tests/phpunit/api/v4/formatExamples/comments.php
@@ -0,0 +1,31 @@
+<?php
+
+return [
+  'html' => '<div>One<!-- uno --> Two <!--dos & so on --> Three</div><!--tres-a--b---c-->',
+  'shallow' => [
+    [
+      '#tag' => 'div',
+      '#children' => [
+        'One',
+        ['#comment' => ' uno '],
+        ' Two ',
+        ['#comment' => 'dos & so on '],
+        ' Three',
+      ],
+    ],
+    ['#comment' => 'tres-a--b---c'],
+  ],
+  'deep' => [
+    [
+      '#tag' => 'div',
+      '#children' => [
+        'One',
+        ['#comment' => ' uno '],
+        ' Two ',
+        ['#comment' => 'dos & so on '],
+        ' Three',
+      ],
+    ],
+    ['#comment' => 'tres-a--b---c'],
+  ],
+];
-- 
2.25.1