Merge branch '4.x' into 5.0

CHANGELOG.md

@@ -4,8 +4,35 @@
 
 ## Unreleased (4.x)
 
+## 4.4.0 - 2024-11-12
+
+- When saving a nested entry within a CKEditor field, the changes are now saved to a draft of the owner element, rather than published immediately. ([craftcms/cms#16002](https://github.com/craftcms/cms/pull/16002), [#308](https://github.com/craftcms/ckeditor/pull/308))
+
+## 4.3.1 - 2024-10-20
+
+- Fixed a bug where sticky toolbars weren’t positioned correctly.
+
+## 4.3.0 - 2024-10-19
+
+- Image toolbars now include an “Edit Image” button. ([#253](https://github.com/craftcms/ckeditor/issues/253))
+- The `ckeditor/convert/redactor` command now ensures that it’s being run interactively.
+- CKEditor container divs now have `data-config` attributes, set to the CKEditor config’s handle. ([#284](https://github.com/craftcms/ckeditor/issues/284))
+- Fixed a bug where page breaks were being lost.
+- Fixed a bug where menus within overflown toolbar items weren’t fully visible. ([#286](https://github.com/craftcms/ckeditor/issues/286))
+- Fixed an error that occurred when editing a nested entry, if it didn’t exist in the primary site. ([#295](https://github.com/craftcms/ckeditor/issues/295))
+
+## 4.2.0 - 2024-08-15
+
 - CKEditor now requires Craft CMS 5.3+.
+- Added the `ckeditor/convert/matrix` command. ([#234](https://github.com/craftcms/ckeditor/pull/234))
 - CKEditor fields can now be merged together. ([#277](https://github.com/craftcms/ckeditor/pull/277))
+- CKEditor configs created via the `ckeditor/convert` command now allow modifying HTML attributes, classes, and styles within the source view, if the Redactor config included the `html` button. ([#264](https://github.com/craftcms/ckeditor/pull/264), [#263](https://github.com/craftcms/ckeditor/issues/263))
+- Added `craft\ckeditor\migrations\BaseConvertMatrixContentMigration`.
+- Fixed a bug where CKEditor fields’ search keywords were including nested entries’ rendered partial templates rather than nested entries’ search keywords.
+- Fixed a bug where nested entries weren’t always getting propagated correctly. ([#254](https://github.com/craftcms/ckeditor/issues/254))
+- Fixed a bug where code blocks created by a Redactor field only had `<pre>` tags with no `<code>` tags inside them. ([#258](https://github.com/craftcms/ckeditor/issues/258))
+- Fixed a bug where dropdown menus didn’t have a maximum height. ([#268](https://github.com/craftcms/ckeditor/issues/268))
+- Fixed a bug where word counts weren’t handling unicode characters correctly. ([#275](https://github.com/craftcms/ckeditor/issues/275))
 
 ## 4.1.0 - 2024-06-12
 

README.md

@@ -18,11 +18,12 @@ This plugin adds a “CKEditor” field type to Craft CMS, which provides a deep
   - [Setup](#setup)
   - [Rendering Nested Entries on the Front End](#rendering-nested-entries-on-the-front-end)
 - [Converting Redactor Fields](#converting-redactor-fields)
+- [Converting Matrix Fields](#converting-matrix-fields)
 - [Adding CKEditor Plugins](#adding-ckeditor-plugins)
 
 ## Requirements
 
-This plugin requires Craft CMS 5.2.0 or later.
+This plugin requires Craft CMS 5.3.0 or later.
 
 ## Installation
 
@@ -57,6 +58,59 @@ New configs can also be created inline from CKEditor field settings.
 
 ![A “Create a new field” page within the Craft CMS control panel, with “CKEditor” as the chosen field type. A slideout is open with CKEditor config settings.](images/field-settings.png)
 
+Once you have selected which toolbar buttons should be available in fields using a given configuration, additional settings may be applied via **Config options**. Options can be defined as static JSON, or a dynamically-evaluated JavaScript snippet; the latter is used as the body of an [immediately-invoked function expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), and does not receive any arguments.
+
+> [!NOTE]  
+> Available options can be found in the [CKEditor's documentation](https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editorconfig-EditorConfig.html). Craft will auto-complete config properties for most bundled CKEditor extensions.
+
+### Examples
+
+#### Table Features
+
+Suppose we wanted to give editors more control over the layout and appearance of in-line tables. Whenever you add the “Insert table” button to an editor, inline controls are exposed for _Table Row_, _Table Column_, and _Merge_. These can be supplemented with _Table Properties_, _Table Cell Properties_, and _Table Caption_ buttons by adding them in the field’s **Config options** section:
+
+```json
+{
+  "table": {
+    "contentToolbar": [
+      "tableRow",
+      "tableColumn",
+      "mergeTableCells",
+      "toggleTableCaption",
+      "tableProperties",
+      "tableCellProperties"
+    ]
+  }
+}
+```
+
+Some of these additional buttons can be customized further. For example, to modify the colors available for a cell’s background (within the “[Table Cell Properties](https://ckeditor.com/docs/ckeditor5/latest/api/module_table_tableconfig-TableConfig.html#member-tableCellProperties)” balloon), you would provide an array compatible with the [`TableColorConfig` schema](https://ckeditor.com/docs/ckeditor5/latest/api/module_table_tableconfig-TableColorConfig.html) under `table.tableCellProperties.backgroundColors`.
+
+#### External Links
+
+Multiple configuration concerns can coexist in one **Config options** object! You might have a `table` key at the top level to customize table controls (as we've done above), as well as a `link` key that introduces “external” link support:
+
+```json
+{
+  "table": { /* ... */ },
+  "link": {
+    "decorators": {
+      "openInNewTab": {
+        "mode": "manual",
+        "label": "Open in new tab?",
+        "attributes": {
+          "target": "_blank",
+          "rel": "noopener noreferrer"
+        }
+      }
+    }
+  }
+}
+```
+
+> [!TIP]  
+> An automatic version of this feature is available natively, via the [`link.addTargetToExternalLinks`](https://ckeditor.com/docs/ckeditor5/latest/api/module_link_linkconfig-LinkConfig.html#member-addTargetToExternalLinks) option.
+
 ### Registering Custom Styles
 
 CKEditor’s [Styles](https://ckeditor.com/docs/ckeditor5/latest/features/style.html) plugin makes it easy to apply custom styles to your content via CSS classes.
@@ -237,12 +291,22 @@ This example treats both chunk types as strings. For entry chunks, this is equiv
 
 ## Converting Redactor Fields
 
-You can used the `ckeditor/convert` command to convert any existing Redactor fields over to CKEditor. For each unique Redactor config, a new CKEditor config will be created.
+You can use the `ckeditor/convert/redactor` command to convert any existing Redactor fields over to CKEditor. For each unique Redactor config, a new CKEditor config will be created and associated with the appropriate field(s).
 
 ```sh
-php craft ckeditor/convert
+php craft ckeditor/convert/redactor
 ```
 
+## Converting Matrix Fields
+
+You can use the `ckeditor/convert/matrix` command to convert a Matrix field over to CKEditor. Each of the Matrix field’s entry types will be assigned to the CKEditor field, and field values will be a mix of HTML content extracted from one of the nested entry types of your choosing (if desired) combined with nested entries.
+
+```sh
+php craft ckeditor/convert/matrix <myMatrixFieldHandle>
+```
+
+The command will generate a new content migration, which will need to be run on other environments (via `craft up`) in order to update existing elements’ field values.
+
 ## Adding CKEditor Plugins
 
 Craft CMS plugins can register additional CKEditor plugins to extend its functionality.
@@ -252,7 +316,8 @@ The first step is to create a [DLL-compatible](https://ckeditor.com/docs/ckedito
 - If you’re including one of CKEditor’s [first-party packages](https://github.com/ckeditor/ckeditor5/tree/master/packages), it will already include a `build` directory with a DLL-compatible package inside it.
 - If you’re creating a custom CKEditor plugin, use [CKEditor’s package generator](https://ckeditor.com/docs/ckeditor5/latest/framework/plugins/package-generator/using-package-generator.html) to scaffold it, and run its [`dll:build` command](https://ckeditor.com/docs/ckeditor5/latest/framework/plugins/package-generator/javascript-package.html#dllbuild) to create a DLL-compatible package.
 
-> :bulb: Check out CKEditor’s [Implementing an inline widget](https://ckeditor.com/docs/ckeditor5/latest/framework/tutorials/implementing-an-inline-widget.html) tutorial for an in-depth look at how to create a custom CKEditor plugin.
+> [!TIP]  
+> Check out CKEditor’s [Implementing an inline widget](https://ckeditor.com/docs/ckeditor5/latest/framework/tutorials/implementing-an-inline-widget.html) tutorial for an in-depth look at how to create a custom CKEditor plugin.
 
 Once the CKEditor package is in place in your Craft plugin, create an [asset bundle](https://craftcms.com/docs/4.x/extend/asset-bundles.html) which extends [`BaseCkeditorPackageAsset`](src/web/assets/BaseCkeditorPackageAsset.php). The asset bundle defines the package’s build directory, filename, a list of CKEditor plugin names provided by the package, and any toolbar items that should be made available via the plugin.
 

composer.json

@@ -25,7 +25,7 @@
   },
   "require": {
     "php": "^8.2",
-    "craftcms/cms": "^5.3.0",
+    "craftcms/cms": "^5.5.0",
     "craftcms/html-field": "^3.1.0",
     "nystudio107/craft-code-editor": ">=1.0.8 <=1.0.13 || ^1.0.16"
   },