Update method for loading first party plugins

craftcms · Feb 18, 2025 · 347af19 · 347af19
1 parent a6f892c
commit 347af19
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -312,20 +312,24 @@ The command will generate a new content migration, which will need to be run on
 ## Adding CKEditor Plugins
 
 ### First Party plugins
-If you'd like to include any of the [first party packages](https://github.com/ckeditor/ckeditor5/tree/master/packages) from CKEditor, you can add them to the `extraPlugins` property on the `ModifyConfigEvent`.
+If you'd like to include any of the [first party packages](https://github.com/ckeditor/ckeditor5/tree/master/packages) from CKEditor, you can call `CkeditorConfig::registerFirstPartyPackage()` in the `init` function of a custom module.
 
 ```php
-use craft\ckeditor\events\ModifyConfigEvent;
-use craft\ckeditor\Field;
-use yii\base\Event;
+use craft\ckeditor\helpers\CkeditorConfig;
 
-Event::on(
-    Field::class,
-    Field::EVENT_MODIFY_CONFIG,
-    handler: function(ModifyConfigEvent $event) {
-        $event->extraPlugins = ['ImageResize'];
+class Site extends BaseModule
+{
+    public function init(): void
+    {
+        parent::init(); 
+
+        // Register a package with toolbar items and multiple plugins
+        CkeditorConfig::registerFirstPartyPackage(['SpecialCharacters', 'SpecialCharactersEssentials'], ['specialCharacters']);
+
+        // Register a package with a single plugin.
+        CkeditorConfig::registerFirstPartyPackage(['ImageResize']);
     }
-);
+}
 ```
 
 ### Custom plugins

diff --git a/src/Field.php b/src/Field.php
@@ -965,7 +965,6 @@ protected function inputHtml(mixed $value, ?ElementInterface $element, $inline):
             'baseConfig' => $baseConfig,
             'ckeConfig' => $ckeConfig,
             'toolbar' => $toolbar,
-            'extraPlugins' => [],
         ]);
         $this->trigger(self::EVENT_MODIFY_CONFIG, $event);
 
@@ -998,8 +997,9 @@ protected function inputHtml(mixed $value, ?ElementInterface $element, $inline):
             $removePlugins->push('ImageTransforms');
         }
 
+        // TODO remove plugins not in toolbar
+
         $plugins = CkeditorConfig::getPluginsByPackage();
-        $plugins['ckeditor5'] = array_merge($plugins['ckeditor5'], $event->extraPlugins);
 
         $plugins = collect($plugins)
             ->mapWithKeys(fn(array $plugins, string $import) => [
@@ -1009,12 +1009,7 @@ protected function inputHtml(mixed $value, ?ElementInterface $element, $inline):
 
         $configPlugins = '[' . $plugins->flatten()->join(',') . ']';
 
-        $imports = $plugins
-            ->reduce(function(Collection $carry, Collection $plugins, string $import) {
-                $carry->push('import { ' . $plugins->join(', ') . ' } from "' . $import . '";');
-                return $carry;
-            }, Collection::empty())
-        ->join("\n");
+        $imports = CkeditorConfig::getImportStatements();
 
         // Add the translation import
         $uiLanguage = BaseCkeditorPackageAsset::uiLanguage();

diff --git a/src/events/ModifyConfigEvent.php b/src/events/ModifyConfigEvent.php
@@ -33,10 +33,4 @@ class ModifyConfigEvent extends Event
      * @since 4.1.0
      */
     public array $toolbar;
-
-    /**
-     * @var string[] $extraPlugins Additional first-party CKEditor plugins to load.
-     * @since 5.0
-     */
-    public array $extraPlugins;
 }
diff --git a/src/helpers/CkeditorConfig.php b/src/helpers/CkeditorConfig.php
@@ -6,6 +6,11 @@
 
 final class CkeditorConfig
 {
+    /**
+     * @see self::registerPackage()
+     * @see self::registerFirstPartyPackage()
+     * @var array|array[] plugins registered keyed by the package namespace
+     */
     private static array $pluginsByPackage = [
         'ckeditor5' => [
             'Bookmark',
@@ -108,17 +113,54 @@ final class CkeditorConfig
     ];
 
 
+    /**
+     * Register a custom CKEditor plugin
+     *
+     * @param string $name the namespace of the plugin
+     * @param array $config plugins and toolbar items created by the plugin
+     * @return void
+     */
     public static function registerPackage(string $name, array $config): void
     {
-        self::$pluginsByPackage[$name] = $config['plugins'] ?? [];
+        $plugins = $config['plugins'] ?? [];
+
+        if (!isset(self::$pluginsByPackage[$name])) {
+            self::$pluginsByPackage[$name] = $plugins;
+        } else {
+            self::$pluginsByPackage[$name] = array_merge(self::$pluginsByPackage[$name], $plugins);
+        }
+
         self::$toolbarItems[] = $config['toolbarItems'] ?? [];
     }
 
+    /**
+     * Register a first party plugin
+     *
+     * @param array $pluginNames plugins to register
+     * @param array $toolbarItems toolbar items to add
+     * @return void
+     */
+    public static function registerFirstPartyPackage(array $pluginNames, array $toolbarItems = []): void
+    {
+        self::registerPackage('ckeditor5', ['plugins' => $pluginNames, 'toolbarItems' => $toolbarItems]);
+    }
+
+    /**
+     * Get all the package namespaces registered
+     *
+     * @return array
+     */
     public static function getPluginPackages(): array
     {
         return array_keys(self::$pluginsByPackage);
     }
 
+    /**
+     * Get the plugins associated with a specific namespace
+     *
+     * @param string|null $name namespace of the package
+     * @return array|array[]|string[] plugins registered from the package
+     */
     public static function getPluginsByPackage(string $name = null): array
     {
         if (!$name) {
@@ -132,22 +174,34 @@ public static function getPluginsByPackage(string $name = null): array
         return self::$pluginsByPackage[$name];
     }
 
+    /**
+     * Return all plugins, regardless of namespace
+     *
+     * @return array
+     */
     public static function getAllPlugins(): array
     {
         return collect(self::getPluginsByPackage())
             ->flatten()
             ->toArray();
     }
 
-    public static function getImportStatements(): string
+    /**
+     * Get the JavaScript import statements for all plugins
+     *
+     * @param string|null $name namespace of the package
+     * @return string
+     */
+    public static function getImportStatements(string $name = null): string
     {
-        return collect(self::getPluginsByPackage())
+        return collect(self::getPluginsByPackage($name))
             ->reduce(function(Collection $carry, array $plugins, string $import) {
                 $carry->push('import { ' . implode(', ', $plugins) . ' } from "' . $import . '";');
 
                 return $carry;
             }, Collection::empty())->join("\n");
     }
+
     private static function normalizeToolbarItem($item): array
     {
         if (is_string($item)) {
@@ -163,7 +217,13 @@ private static function normalizeToolbarItem($item): array
         return [$item];
     }
 
-    public static function normalizeToolbarItems($items): array
+    /**
+     * Normalizes toolbar items
+     *
+     * @param array $items toolbar items
+     * @return array normalized toolbar items
+     */
+    public static function normalizeToolbarItems(array $items): array
     {
         return collect($items)
             ->map(fn($item) => self::normalizeToolbarItem($item))