Merge pull request #11035 from engram-design/4.0

Add `Element::getElementHtml()` to allow elements to define their own HTML for the element icon
craftcms · Apr 28, 2022 · da896b9 · da896b9
2 parents a9e0493 + d853161
commit da896b9
Showing 5 changed files with 93 additions and 8 deletions.
diff --git a/CHANGELOG-WIP.md b/CHANGELOG-WIP.md
@@ -209,6 +209,7 @@
 - Added `craft\events\AuthorizationCheckEvent`.
 - Added `craft\events\CreateElementCheckEvent`.
 - Added `craft\events\DefineElementEditorHtmlEvent`.
+- Added `craft\events\DefineElementInnerHtmlEvent`. ([#11035](https://github.com/craftcms/cms/pull/11035))
 - Added `craft\events\DefineHtmlEvent::$static`.
 - Added `craft\events\FsEvent`.
 - Added `craft\events\GenerateTransformEvent::$asset`.
@@ -268,6 +269,7 @@
 - Added `craft\helpers\Cp::dateFieldHtml()`.
 - Added `craft\helpers\Cp::dateHtml()`.
 - Added `craft\helpers\Cp::elementSelectHtml()`.
+- Added `craft\helpers\Cp::EVENT_DEFINE_ELEMENT_INNER_HTML`. ([#11035](https://github.com/craftcms/cms/pull/11035))
 - Added `craft\helpers\Cp::fieldLayoutDesignerHtml()`.
 - Added `craft\helpers\Cp::lightswitchHtml()`.
 - Added `craft\helpers\Cp::multiSelectFieldHtml()`.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Added
 - Added `craft\base\PluginInterface::config()`. ([#11039](https://github.com/craftcms/cms/pull/11039))
+- Added `craft\events\DefineElementInnerHtmlEvent`. ([#11035](https://github.com/craftcms/cms/pull/11035))
+- Added `craft\helpers\Cp::EVENT_DEFINE_ELEMENT_INNER_HTML`. ([#11035](https://github.com/craftcms/cms/pull/11035))
 - Added `craft\helpers\Html::unwrapCondition()`.
 - Added `craft\helpers\Html::unwrapNoscript()`.
 - Added `craft\web\View::clearCssFileBuffer()`.

diff --git a/src/controllers/AppController.php b/src/controllers/AppController.php
@@ -679,7 +679,7 @@ public function actionRenderElement(): Response
                 $elementHtml[] = Cp::elementHtml(
                     $elements[$instance['siteId']],
                     $instance['context'],
-                    $instance['thumbSize'],
+                    $instance['size'],
                     null,
                     $instance['showStatus'],
                     $instance['showThumb'],

diff --git a/src/events/DefineElementInnerHtmlEvent.php b/src/events/DefineElementInnerHtmlEvent.php
@@ -0,0 +1,61 @@
+<?php
+/**
+ * @link https://craftcms.com/
+ * @copyright Copyright (c) Pixel & Tonic, Inc.
+ * @license https://craftcms.github.io/license/
+ */
+
+namespace craft\events;
+
+use craft\base\ElementInterface;
+
+use yii\base\Event;
+
+/**
+ * DefineElementInnerHtmlEvent class.
+ *
+ * @author Pixel & Tonic, Inc. <[email protected]>
+ * @since 4.0.0
+ */
+class DefineElementInnerHtmlEvent extends Event
+{
+    /**
+     * @var ElementInterface The element being rendered via `\craft\helpers\Cp::elementHtml()`.
+     */
+    public ElementInterface $element;
+
+    /**
+     * @var string The context the element is going to be shown in (`index`, `field`, etc.).
+     */
+    public string $context;
+
+    /**
+     * @var string The size of the element (`small` or `large`).
+     */
+    public string $size;
+
+    /**
+     * @var bool Whether the element status should be shown (if the element type has statuses).
+     */
+    public bool $showStatus;
+
+    /**
+     * @var bool Whether the element thumb should be shown (if the element has one).
+     */
+    public bool $showThumb;
+
+    /**
+     * @var bool Whether the element label should be shown.
+     */
+    public bool $showLabel;
+
+    /**
+     * @var bool Whether to show the draft name beside the label if the element is a draft of a published element.
+     */
+    public bool $showDraftName;
+
+    /**
+     * @var string The element’s pre-rendered inner HTML.
+     */
+    public string $innerHtml;
+}
diff --git a/src/helpers/Cp.php b/src/helpers/Cp.php
@@ -13,6 +13,7 @@
 use craft\behaviors\DraftBehavior;
 use craft\elements\Address;
 use craft\enums\LicenseKeyStatus;
+use craft\events\DefineElementInnerHtmlEvent;
 use craft\events\RegisterCpAlertsEvent;
 use craft\fieldlayoutelements\BaseField;
 use craft\models\FieldLayout;
@@ -37,6 +38,12 @@ class Cp
      */
     public const EVENT_REGISTER_ALERTS = 'registerAlerts';
 
+    /**
+     * @event DefineElementInnerHtmlEvent The event that is triggered when defining an element’s inner HTML.
+     * @since 4.0.0
+     */
+    public const EVENT_DEFINE_ELEMENT_INNER_HTML = 'defineElementInnerHtml';
+
     /**
      * @since 3.5.8
      */
@@ -239,7 +246,7 @@ public static function alerts(?string $path = null, bool $fetch = false): array
      *
      * @param ElementInterface $element The element to be rendered
      * @param string $context The context the element is going to be shown in (`index`, `field`, etc.)
-     * @param string $thumbSize The size of the element (`small` or `large`)
+     * @param string $size The size of the element (`small` or `large`)
      * @param string|null $inputName The `name` attribute that should be set on the hidden input, if `$context` is set to `field`
      * @param bool $showStatus Whether the element status should be shown (if the element type has statuses)
      * @param bool $showThumb Whether the element thumb should be shown (if the element has one)
@@ -253,7 +260,7 @@ public static function alerts(?string $path = null, bool $fetch = false): array
     public static function elementHtml(
         ElementInterface $element,
         string $context = 'index',
-        string $thumbSize = self::ELEMENT_SIZE_SMALL,
+        string $size = self::ELEMENT_SIZE_SMALL,
         ?string $inputName = null,
         bool $showStatus = true,
         bool $showThumb = true,
@@ -269,7 +276,7 @@ public static function elementHtml(
 
         // Create the thumb/icon image, if there is one
         if ($showThumb) {
-            $thumbSizePx = $thumbSize === self::ELEMENT_SIZE_SMALL ? 34 : 120;
+            $thumbSizePx = $size === self::ELEMENT_SIZE_SMALL ? 34 : 120;
             $thumbUrl = $element->getThumbUrl($thumbSizePx);
         } else {
             $thumbSizePx = $thumbUrl = null;
@@ -289,7 +296,7 @@ public static function elementHtml(
                 'class' => array_filter([
                     'elementthumb',
                     $element->getHasCheckeredThumb() ? 'checkered' : null,
-                    $thumbSize === self::ELEMENT_SIZE_SMALL && $element->getHasRoundedThumb() ? 'rounded' : null,
+                    $size === self::ELEMENT_SIZE_SMALL && $element->getHasRoundedThumb() ? 'rounded' : null,
                 ]),
                 'data' => [
                     'sizes' => $sizesHtml,
@@ -304,7 +311,7 @@ public static function elementHtml(
         $attributes = ArrayHelper::merge(
             Html::normalizeTagAttributes($element->getHtmlAttributes($context)),
             [
-                'class' => ['element', $thumbSize],
+                'class' => ['element', $size],
                 'title' => $label . (Craft::$app->getIsMultiSite() ? ' – ' . Craft::t('site', $element->getSite()->getName()) : ''),
                 'data' => array_filter([
                     'type' => get_class($element),
@@ -318,7 +325,7 @@ public static function elementHtml(
                     'level' => $element->level,
                     'settings' => $autoReload ? compact(
                         'context',
-                        'thumbSize',
+                        'size',
                         'showStatus',
                         'showThumb',
                         'showLabel',
@@ -425,7 +432,20 @@ public static function elementHtml(
             $innerHtml .= '</span></div>';
         }
 
-        return Html::tag('div', $innerHtml, $attributes);
+        // Allow plugins to modify the inner HTML
+        $event = new DefineElementInnerHtmlEvent(compact(
+            'element',
+            'context',
+            'size',
+            'showStatus',
+            'showThumb',
+            'showLabel',
+            'showDraftName',
+            'innerHtml',
+        ));
+        Event::trigger(self::class, self::EVENT_DEFINE_ELEMENT_INNER_HTML, $event);
+
+        return Html::tag('div', $event->innerHtml, $attributes);
     }
 
     /**