Add extension point for custom stored Font Awesome icons

Allow FontAwesomeIcon to resolve non-native stored icon strings through a new StoredIconResolving event. This keeps native `name;solid` icon strings unchanged while giving packages a package-safe way to provide custom IFontAwesomeIcon implementations for extended descriptors.

Also extend the FontAwesome picker callback contract with optional stored value and preview HTML arguments, and update IconFormField and trophy badge preview handling to use those optional values when provided.

Author: SoftCreatR

com.woltlab.wcf/templates/shared_iconFormField.tpl

@@ -13,34 +13,43 @@
 	{if $__iconFormFieldIncludeJavaScript}
 		{include file='shared_fontAwesomeJavaScript'}
 	{/if}
-	
+
 	<script data-relocate="true">
 		require(['WoltLabSuite/Core/Ui/Style/FontAwesome'], (UiStyleFontAwesome) => {
 			const iconContainer = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}_icon');
 			const input = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}');
 			const buttonRemoveIcon = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}_removeIcon');
-			
-			const callback = (iconName, forceSolid) => {
-				input.value = `${ iconName };${ forceSolid }`;
 
+			const renderNativePreview = (iconName, forceSolid) => {
 				let icon = iconContainer.querySelector("fa-icon");
-				if (icon) {
-					icon.setIcon(iconName, forceSolid);
-				} else {
+				if (!icon || icon.parentElement !== iconContainer || iconContainer.childElementCount !== 1) {
+					iconContainer.replaceChildren();
+
 					icon = document.createElement("fa-icon");
 					icon.size = 64;
-					icon.setIcon(iconName, forceSolid);
 					iconContainer.append(icon);
 				}
 
+				icon.setIcon(iconName, forceSolid);
+			};
+
+			const callback = (iconName, forceSolid, value, previewHtml) => {
+				input.value = typeof value === 'string' ? value : `${ iconName };${ forceSolid }`;
+
+				if (typeof previewHtml === 'string') {
+					iconContainer.innerHTML = previewHtml;
+				} else {
+					renderNativePreview(iconName, forceSolid);
+				}
+
 				buttonRemoveIcon.hidden = false;
 			};
-			
+
 			const button = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}_openIconDialog');
 			button.addEventListener('click', () => UiStyleFontAwesome.open(callback));
 			buttonRemoveIcon.addEventListener("click", () => {
 				input.value = "";
-				iconContainer.querySelector("fa-icon")?.remove();
+				iconContainer.replaceChildren();
 
 				buttonRemoveIcon.hidden = true;
 			});

ts/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.ts

@@ -13,16 +13,33 @@ import DomUtil from "../../../Dom/Util";
 
 const badgeContainer = document.getElementById("badgeContainer")!;
 const previewWrapper = badgeContainer.querySelector(".trophyIcon") as HTMLElement;
-const previewIcon = previewWrapper.querySelector("fa-icon")!;
+
+function renderNativePreview(icon: string, forceSolid: boolean): void {
+  let previewIcon = previewWrapper.querySelector("fa-icon");
+  if (!(previewIcon instanceof HTMLElement) || previewIcon.parentElement !== previewWrapper) {
+    previewWrapper.replaceChildren();
+
+    previewIcon = document.createElement("fa-icon");
+    previewIcon.size = 64;
+    previewWrapper.append(previewIcon);
+  }
+
+  previewIcon.setIcon(icon, forceSolid);
+}
 
 function setupChangeIcon(): void {
   const button = badgeContainer.querySelector('.trophyIconEditButton[data-value="icon"]') as HTMLButtonElement;
   const input = badgeContainer.querySelector('input[name="iconName"]') as HTMLInputElement;
 
   button.addEventListener("click", () => {
-    openFontAwesomePicker((icon, forceSolid) => {
-      previewIcon.setIcon(icon, forceSolid);
-      input.value = `${icon};${String(forceSolid)}`;
+    openFontAwesomePicker((icon, forceSolid, value, previewHtml) => {
+      input.value = value ?? `${icon};${String(forceSolid)}`;
+
+      if (typeof previewHtml === "string") {
+        previewWrapper.innerHTML = previewHtml;
+      } else {
+        renderNativePreview(icon, forceSolid);
+      }
     });
   });
 }

ts/WoltLabSuite/Core/Ui/Style/FontAwesome.ts

@@ -11,7 +11,7 @@ import { getPhrase } from "WoltLabSuite/Core/Language";
 import UiItemListFilter from "../ItemList/Filter";
 import { dialogFactory } from "WoltLabSuite/Core/Component/Dialog";
 
-type CallbackSelect = (icon: string, forceSolid: boolean) => void;
+type CallbackSelect = (icon: string, forceSolid: boolean, value?: string, previewHtml?: string) => void;
 type IconData = { icon: string; forceSolid: boolean };
 
 function createIconList(): HTMLElement {
@@ -92,7 +92,9 @@ function setupListeners(): void {
 
 /**
  * Shows the FontAwesome selection dialog, supplied callback will be
- * invoked with the selection icon's name as the only argument.
+ * invoked with the selected icon's native data. Replacement
+ * implementations may pass an explicit stored value and preview html
+ * for non-native icons.
  */
 export function open(callback: CallbackSelect): void {
   const dialog = dialogFactory().fromElement(getContent()).asConfirmation();

wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.js

@@ -0,0 +1,24 @@
+<?php
+
+namespace wcf\event\style;
+
+use wcf\event\IPsr14Event;
+use wcf\system\style\IFontAwesomeIcon;
+
+/**
+ * Resolves a stored icon string to a renderable icon instance.
+ *
+ * @author      Sascha Greuel
+ * @copyright   2001-2026 WoltLab GmbH
+ * @license     GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since       6.2
+ */
+final class StoredIconResolving implements IPsr14Event
+{
+    public ?IFontAwesomeIcon $icon = null;
+
+    public function __construct(
+        public readonly string $iconData
+    ) {
+    }
+}

wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Style/FontAwesome.js

@@ -2,6 +2,8 @@
 
 namespace wcf\system\style;
 
+use wcf\event\style\StoredIconResolving;
+use wcf\system\event\EventHandler;
 use wcf\system\style\exception\InvalidIconFormat;
 use wcf\system\style\exception\InvalidIconSize;
 use wcf\system\style\exception\UnknownIcon;
@@ -28,9 +30,13 @@ final class FontAwesomeIcon implements IFontAwesomeIcon, \Stringable
 
     private function __construct(
         private readonly string $name,
-        private readonly bool $forceSolid
+        private readonly bool $forceSolid,
+        private readonly ?string $iconData = null,
+        private readonly ?IFontAwesomeIcon $icon = null
     ) {
-        self::validateName($name);
+        if ($this->icon === null) {
+            self::validateName($name);
+        }
     }
 
     /**
@@ -39,6 +45,10 @@ private function __construct(
      */
     public function __toString(): string
     {
+        if ($this->iconData !== null) {
+            return $this->iconData;
+        }
+
         return \sprintf(
             "%s;%s",
             $this->name,
@@ -55,6 +65,10 @@ public function toHtml(int $size = 16): string
             throw new InvalidIconSize($size);
         }
 
+        if ($this->icon !== null) {
+            return $this->icon->toHtml($size);
+        }
+
         if ($this->forceSolid) {
             return \sprintf(
                 '<fa-icon size="%d" name="%s" solid></fa-icon>',
@@ -79,18 +93,21 @@ public function toHtml(int $size = 16): string
      */
     public static function fromString(string $iconData): self
     {
-        if (!\str_contains($iconData, ';')) {
-            throw new InvalidIconFormat();
+        $icon = self::parseIconData($iconData);
+        if ($icon !== null && self::isValidName($icon['name'])) {
+            return self::fromValues($icon['name'], $icon['forceSolid']);
         }
 
-        [$name, $solid] = \explode(';', $iconData, 2);
-        if ($solid !== 'true' && $solid !== 'false') {
-            throw new InvalidIconFormat();
+        $resolvedIcon = self::resolveStoredIcon($iconData);
+        if ($resolvedIcon !== null) {
+            return new self('question', true, $iconData, $resolvedIcon);
         }
 
-        $forceSolid = $solid === 'true';
+        if ($icon === null) {
+            throw new InvalidIconFormat();
+        }
 
-        return self::fromValues($name, $forceSolid);
+        return self::fromValues($icon['name'], $icon['forceSolid']);
     }
 
     public static function fromValues(string $name, bool $forceSolid = false): self
@@ -99,17 +116,41 @@ public static function fromValues(string $name, bool $forceSolid = false): self
     }
 
     public static function isValidString(string $iconData): bool
+    {
+        $icon = self::parseIconData($iconData);
+        if ($icon !== null && self::isValidName($icon['name'])) {
+            return true;
+        }
+
+        return self::resolveStoredIcon($iconData) !== null;
+    }
+
+    /**
+     * @return ?array{name: string, forceSolid: bool}
+     */
+    private static function parseIconData(string $iconData): ?array
     {
         if (!\str_contains($iconData, ';')) {
-            return false;
+            return null;
         }
 
         [$name, $solid] = \explode(';', $iconData, 2);
         if ($solid !== 'true' && $solid !== 'false') {
-            return false;
+            return null;
         }
 
-        return self::isValidName($name);
+        return [
+            'name' => $name,
+            'forceSolid' => $solid === 'true',
+        ];
+    }
+
+    private static function resolveStoredIcon(string $iconData): ?IFontAwesomeIcon
+    {
+        $event = new StoredIconResolving($iconData);
+        EventHandler::getInstance()->fire($event);
+
+        return $event->icon;
     }
 
     public static function isValidName(string $name): bool