From e564eac67d3fcfee8fad1760e928f6af81e13d22 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 25 Aug 2020 17:11:34 -0700
Subject: [PATCH] CollectionAdderInterface - Support addMarkup($html)

---
 .../Resources/CollectionAdderInterface.php    | 16 ++++++++++++++
 CRM/Core/Resources/CollectionAdderTrait.php   | 21 +++++++++++++++++++
 .../Core/Resources/CollectionTestTrait.php    | 21 +++++++++++++++++--
 3 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/CRM/Core/Resources/CollectionAdderInterface.php b/CRM/Core/Resources/CollectionAdderInterface.php
index 5f7e6b0ead..e3b4f2cc92 100644
--- a/CRM/Core/Resources/CollectionAdderInterface.php
+++ b/CRM/Core/Resources/CollectionAdderInterface.php
@@ -28,6 +28,22 @@ interface CRM_Core_Resources_CollectionAdderInterface {
 
   // TODO public function addBundle($bundle);
 
+  /**
+   * Add an HTML blob.
+   *
+   * Ex: addMarkup('<p>Hello world!</p>', ['weight' => 123]);
+   *
+   * @param string $markup
+   *   HTML code.
+   * @param array $options
+   *   Open-ended list of key-value options. See CollectionInterface docs.
+   *   Positional equivalence: addMarkup(string $code, int $weight, string $region).
+   * @return static
+   * @see CRM_Core_Resources_CollectionInterface
+   * @see CRM_Core_Resources_CollectionAdderInterface::addScript()
+   */
+  public function addMarkup(string $markup, ...$options);
+
   /**
    * Export permission data to the client to enable smarter GUIs.
    *
diff --git a/CRM/Core/Resources/CollectionAdderTrait.php b/CRM/Core/Resources/CollectionAdderTrait.php
index da3ecb2904..da81a34a03 100644
--- a/CRM/Core/Resources/CollectionAdderTrait.php
+++ b/CRM/Core/Resources/CollectionAdderTrait.php
@@ -40,6 +40,27 @@ trait CRM_Core_Resources_CollectionAdderTrait {
    */
   abstract public function &findCreateSettingSnippet($options = []): array;
 
+  /**
+   * Add an HTML blob.
+   *
+   * Ex: addMarkup('<p>Hello world!</p>', ['weight' => 123]);
+   *
+   * @param string $markup
+   *   HTML code.
+   * @param array $options
+   *   Open-ended list of key-value options. See CollectionInterface docs.
+   *   Positional equivalence: addMarkup(string $code, int $weight, string $region).
+   * @return static
+   * @see CRM_Core_Resources_CollectionInterface
+   * @see CRM_Core_Resources_CollectionAdderInterface::addMarkup()
+   */
+  public function addMarkup(string $markup, ...$options) {
+    $this->add(self::mergeStandardOptions($options, [
+      'markup' => $markup,
+    ]));
+    return $this;
+  }
+
   /**
    * Export permission data to the client to enable smarter GUIs.
    *
diff --git a/tests/phpunit/CRM/Core/Resources/CollectionTestTrait.php b/tests/phpunit/CRM/Core/Resources/CollectionTestTrait.php
index 61787dfd48..3b1a069cbb 100644
--- a/tests/phpunit/CRM/Core/Resources/CollectionTestTrait.php
+++ b/tests/phpunit/CRM/Core/Resources/CollectionTestTrait.php
@@ -23,6 +23,8 @@ trait CRM_Core_Resources_CollectionTestTrait {
   abstract public function createEmptyCollection();
 
   public function getSnippetExamples() {
+    $allowsMarkup = ($this instanceof CRM_Core_RegionTest);
+    $defaultCount = ($this instanceof CRM_Core_RegionTest) ? 1 : 0;
     $es = [];
 
     /**
@@ -159,8 +161,7 @@ trait CRM_Core_Resources_CollectionTestTrait {
         'addScript()' => ['addScript', 'window.alert("Boo!");'],
       ],
       [
-        // Regions always have a 'default' with ID#1, so our test always becomes #2.
-        'name' => ($this instanceof CRM_Core_RegionTest ? 2 : 1),
+        'name' => 1 + $defaultCount,
         'disabled' => FALSE,
         'weight' => 1,
         'type' => 'script',
@@ -168,6 +169,22 @@ trait CRM_Core_Resources_CollectionTestTrait {
       ]
     );
 
+    if ($allowsMarkup) {
+      $addCases(
+        [
+          'add(markup)' => ['add', ['markup' => '<p>HELLO</p>']],
+          'addMarkup()' => ['addMarkup', '<p>HELLO</p>'],
+        ],
+        [
+          'name' => 1 + $defaultCount,
+          'disabled' => FALSE,
+          'weight' => 1,
+          'type' => 'markup',
+          'markup' => '<p>HELLO</p>',
+        ]
+      );
+    }
+
     return $es;
   }
 
-- 
2.25.1