diff --git a/README.md b/README.md index 2be7af1..be34bf9 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,23 @@ -# Quill WYSIWYG Pimcore Bundle -This bundle provides the [Quill 2.x](https://quilljs.com/) WYSIWYG editor integration for Pimcore. -This includes the WYSIWYG for Documents, Data Objects and Shared Translations. +--- +title: Quill WYSIWYG Editor +--- -## Installation -See [Installation](./doc/00_Installation/README.md) +# Quill WYSIWYG Editor -## Migration to Quill -See [Migration](./doc/01_Migration_to_Quill.md) +Integrates the [Quill 2.x](https://quilljs.com/) WYSIWYG editor into Pimcore. +Quill provides rich-text editing for documents, data objects, and shared translations. -## Configuration +## Features -Available configuration options can be found here: [config options](https://quilljs.com/docs/configuration/) +- Rich-text editing based on [Quill 2.x](https://quilljs.com/) with built-in + undo/redo and HTML source editing +- WYSIWYG support for document editables, data object fields, and shared translations +- Per-field toolbar configuration through Twig editables +- Global editor defaults through Symfony configuration (`pimcore_studio_ui`) -### Themes +## Documentation Overview -Available themes and how to configure it can be found here: [themes](https://quilljs.com/docs/customization/themes) - -## Examples - -### Basic usage - -`wysiwyg` helper doesn't require any additional configuration options. -The following code customize the toolbar. - -```twig -
- {{ pimcore_wysiwyg("specialContent", { - modules: { - toolbar: { - container: [ - [{ header: [1, 2, 3, 4, 5, 6, false] }] - ] - } - } - }) - }} -
-``` - -### Custom configuration for Quill - -A list of configuration options you can find in the [Quill toolbar documentation](https://quilljs.com/docs/modules/toolbar). -In addition to this you can also configure `undo`, `redo` and `html-edit`. - -The WYSIWYG editable allows us to specify the toolbar. -If you have to limit styling options (for example only basic styles like `` tag and lists would be allowed), just use `toolbar` option. - -```twig -
- {{ pimcore_wysiwyg("specialContent", { - modules: { - toolbar: { - container: [ - ['undo', 'redo'], - [{ header: [1, 2, 3, 4, 5, 6, false] }], - ['html-edit'] - ] - } - } - }) - }} -
-``` - -Now the user can use only the limited toolbar. - -##### Global Configuration -See [admin-ui-classic-bundle](./doc/02_Global_Configuration_Admin_Ui.md) -See [studio-ui-bundle](./doc/03_Global_Configuration_Studio_Ui.md) +- [Installation](./doc/00_Installation/README.md) +- [Configuration](./doc/02_Configuration.md) - toolbar options, global defaults, and themes +- [Migration from TinyMCE](./doc/03_Migration_to_Quill.md) +- [Upgrade Information](./doc/00_Installation/01_Upgrade.md) diff --git a/doc/00_Installation/01_Upgrade.md b/doc/00_Installation/01_Upgrade.md index a55c9f7..2f089a8 100644 --- a/doc/00_Installation/01_Upgrade.md +++ b/doc/00_Installation/01_Upgrade.md @@ -1,7 +1,27 @@ -# Upgrade Information +--- +title: Upgrade Information +--- -Following steps are necessary during updating to newer versions. +# Upgrade Information ## Upgrade to 2026.1.0 -- Added support to `PHP` `8.5`. -- Removed support to `PHP` `8.3` and Symfony `v6`. \ No newline at end of file + +### PHP / Symfony Requirements + +- Added support for PHP 8.5 +- Dropped PHP 8.3 and Symfony 6 support — upgrade to PHP 8.4+ and Symfony 7 before updating to this version + +### Removed Admin Classic UI (ExtJS) Support + +The bundle no longer supports the Pimcore Admin Classic UI (ExtJS). All ExtJS-related +code and assets have been removed: + +- `PimcoreQuillBundle` no longer implements `PimcoreBundleAdminClassicInterface` and no longer uses `BundleAdminClassicTrait` +- Removed methods: `getJsPaths()`, `getCssPaths()`, `getEditmodeCssPaths()`, `getEditmodeJsPaths()` (from `BundleAdminClassicTrait`) +- All classic admin public assets have been removed: + - `public/js/editor.js` + - `public/css/editor.css` and icon assets under `public/css/icons/` + - Quill library assets under `public/quill/` and `public/quill-table-better/` + +The bundle now exclusively supports the Pimcore Studio UI. `pimcore/studio-ui-bundle` +and `pimcore/studio-backend-bundle` are now required dependencies. diff --git a/doc/00_Installation/README.md b/doc/00_Installation/README.md index cbb28ea..809ad80 100644 --- a/doc/00_Installation/README.md +++ b/doc/00_Installation/README.md @@ -1,18 +1,33 @@ -# Installation - -```bash -composer require pimcore/quill-bundle -``` - -Make sure the bundle is enabled in the `config/bundles.php` file. The following lines should be added: - -```php -use Pimcore\Bundle\QuillBundle\PimcoreQuillBundle; -// ... - -return [ - // ... - PimcoreQuillBundle::class => ['all' => true], - // ... -]; -``` \ No newline at end of file +--- +title: Installation +--- + +# Installation + +## Requirements + +- PHP 8.5 +- Pimcore 2026.1 or later +- Studio UI bundle 0.12.9 or later + +## Install + +```bash +composer require pimcore/quill-bundle +``` + +Enable the bundle in `config/bundles.php`: + +```php +use Pimcore\Bundle\QuillBundle\PimcoreQuillBundle; +// ... + +return [ + // ... + PimcoreQuillBundle::class => ['all' => true], + // ... +]; +``` + +For toolbar and theme options, see [Configuration](../02_Configuration.md). +If you are replacing TinyMCE, see [Migration from TinyMCE](../03_Migration_to_Quill.md). diff --git a/doc/01_Migration_to_Quill.md b/doc/01_Migration_to_Quill.md deleted file mode 100644 index 345a146..0000000 --- a/doc/01_Migration_to_Quill.md +++ /dev/null @@ -1,34 +0,0 @@ -# Migration to Quill - -Every WYSIWYG-Editor (TinyMCE, CKEditor, ...) has its own peculiarities, that means that they are never 100% compatible to each other. Potential incompatibilities can result into different markup or styling, in rare edge-cases even in a kind of data-loss if the existing markup is not supported by Quill. Therefore it's important to check your existing contents for compatibility with the editor. - -## Replace TinyMCE with Quill - -First install Quill: [Installation](./00_Installation/README.md) - -### Bundles - -Make sure TinyMCE isn't enabled in the `config/bundles.php` file. The following lines should be removed: - -```php -use Pimcore\Bundle\TinymceBundle\PimcoreTinymceBundle; -// ... - -return [ - // ... - PimcoreTinymceBundle::class => ['all' => true], - // ... -]; -``` - -## Known incompatibilities - -### Configuration - -Change the twig and public configs according to [config options](https://quilljs.com/docs/configuration/) - -### Tables & Lists - -Tables & Lists form TinyMCE could be displayed different in Quill than in TinyMCE. Please check your fields after migration. - - diff --git a/doc/02_Configuration.md b/doc/02_Configuration.md new file mode 100644 index 0000000..186f21c --- /dev/null +++ b/doc/02_Configuration.md @@ -0,0 +1,110 @@ +--- +title: Configuration +--- + +# Configuration + +The Quill editor supports configuration through Pimcore editables (per-field) and +Symfony configuration (global defaults). + +## Default Toolbar + +When no custom toolbar is configured, the editor uses this default: + +``` +undo, redo | H1-H6 headings | bold, italic | alignment | +ordered list, bullet list | indent, outdent | blockquote | +link, table | clean, html-edit +``` + +## Toolbar Configuration in Twig + +The `pimcore_wysiwyg` editable accepts Quill configuration options directly. +Use the `modules.toolbar.container` array to define which toolbar controls are available. + +### Basic example + +```twig +{{ pimcore_wysiwyg("content", { + modules: { + toolbar: { + container: [ + [{ header: [1, 2, 3, 4, 5, 6, false] }] + ] + } + } + }) +}} +``` + +### Toolbar with undo, redo, and HTML editing + +In addition to [standard Quill toolbar options](https://quilljs.com/docs/modules/toolbar), +the bundle provides `undo`, `redo`, and `html-edit` controls. + +```twig +{{ pimcore_wysiwyg("content", { + modules: { + toolbar: { + container: [ + ['undo', 'redo'], + [{ header: [1, 2, 3, 4, 5, 6, false] }], + ['html-edit'] + ] + } + } + }) +}} +``` + +Controls not listed in the `container` array are excluded from the toolbar. + +## Global Configuration + +Global WYSIWYG defaults are configured under the `pimcore_studio_ui` extension +provided by the Studio UI bundle. The Quill bundle does not define its own +configuration namespace. + +These defaults apply to all WYSIWYG fields unless overridden per-field in Twig. + +```yaml +# config/packages/pimcore_studio_ui.yaml +pimcore_studio_ui: + wysiwyg: + defaultEditorConfig: + dataObject: + modules: + toolbar: + container: + - [{ header: [1, 2, 3, 4, 5, 6, false] }] + document: + modules: + toolbar: + container: + - [{ header: [1, 2, 3, 4, 5, 6, false] }] +``` + +- `dataObject` - applies to WYSIWYG fields in data object classes +- `document` - applies to WYSIWYG editables in documents +- Per-field configuration in Twig overrides these global defaults +- Shared translations use the Quill editor but do not have a separate global config key + +:::note +The configuration structure under `dataObject` and `document` follows the +[Quill configuration format](https://quilljs.com/docs/configuration/). +::: + +## Themes + +Quill supports multiple themes that control the editor's appearance. +Set the theme in the Quill configuration options: + +```twig +{{ pimcore_wysiwyg("content", { + theme: "snow" + }) +}} +``` + +See the [Quill themes documentation](https://quilljs.com/docs/customization/themes) +for available themes. diff --git a/doc/02_Global_Configuration_Admin_Ui.md b/doc/02_Global_Configuration_Admin_Ui.md deleted file mode 100644 index 47f3986..0000000 --- a/doc/02_Global_Configuration_Admin_Ui.md +++ /dev/null @@ -1,98 +0,0 @@ -##### Global Configuration (only for admin-ui-classic-bundle) - -You can add a Global Configuration for all WYSIWYG Editors for all documents by setting `pimcore.document.editables.wysiwyg.defaultEditorConfig`. -You can add a Global Configuration for all WYSIWYG Editors for all data objects by setting `pimcore.object.tags.wysiwyg.defaultEditorConfig`. - -For this purpose, you can create a [Pimcore Bundle](https://pimcore.com/docs/pimcore/current/Development_Documentation/Extending_Pimcore/Bundle_Developers_Guide/index.html) and add the -configuration in a file in the `Resources/public` directory of your bundle (e.g. `Resources/public/js/editmode.js`). - -``` -pimcore.document.editables.wysiwyg = pimcore.document.editables.wysiwyg || {}; -pimcore.document.editables.wysiwyg.defaultEditorConfig = { menubar: true }; -``` -This will show you the default menubar from Quill in all document editables. - -For the data object settings, you should put them in the `startup.js` in your bundle. -``` -pimcore.registerNS("pimcore.plugin.YourQuillEditorConfigBundle"); - -pimcore.plugin.YourQuillEditorConfigBundle = Class.create({ - - initialize: function () { - document.addEventListener(pimcore.events.pimcoreReady, this.pimcoreReady.bind(this)); - }, - - pimcoreReady: function (e) { - pimcore.object.tags.wysiwyg = pimcore.object.tags.wysiwyg || {}; - pimcore.object.tags.wysiwyg.defaultEditorConfig = { menubar: true }; - } -}); - -const YourQuillEditorConfigBundlePlugin = new pimcore.plugin.YourQuillEditorConfigBundle(); -``` - - - -To load the `editmode.js` file in editmode, you need to implement `getEditmodeJsPaths` in your bundle class. Given your bundle is named -`AppAdminBundle` and your `editmode.js` and `startup.js` created before was saved to `src/AppAdminBundle/public/js/editmode.js` and `src/AppAdminBundle/public/js/startup.js`: - -```php - 'onEditmodeJsPaths' - ]; - } - - public function onEditmodeJsPaths(PathsEvent $event): void - { - $event->addPaths([ - '/bundles/app/js/pimcore/editmode.js' - ]); - } -} -``` diff --git a/doc/03_Global_Configuration_Studio_Ui.md b/doc/03_Global_Configuration_Studio_Ui.md deleted file mode 100644 index b1e42d6..0000000 --- a/doc/03_Global_Configuration_Studio_Ui.md +++ /dev/null @@ -1,3 +0,0 @@ -##### Global Configuration (only for studio-ui-bundle) - -You can add a Global Configuration with the [symfony config](https://docs.pimcore.com/platform/Studio_UI/Configuration/Wysiwyg) from studio-ui-bundle diff --git a/doc/03_Migration_to_Quill.md b/doc/03_Migration_to_Quill.md new file mode 100644 index 0000000..ccba7c1 --- /dev/null +++ b/doc/03_Migration_to_Quill.md @@ -0,0 +1,44 @@ +--- +title: Migration from TinyMCE +--- + +# Migration from TinyMCE + +Every WYSIWYG editor (TinyMCE, CKEditor, etc.) produces different markup. +Migrating between editors can result in different styling or formatting, +and in rare cases content that the new editor does not support. +Review existing content for compatibility after switching. + +## Replace TinyMCE with Quill + +1. Install the Quill bundle - see [Installation](./00_Installation/README.md) + +2. Remove TinyMCE: + + ```bash + composer remove pimcore/tinymce-bundle + ``` + + This also removes it from `config/bundles.php` if Symfony Flex is active. + Otherwise, manually remove the bundle registration: + + ```php + // Remove these lines from config/bundles.php: + use Pimcore\Bundle\TinymceBundle\PimcoreTinymceBundle; + + return [ + // Remove: + PimcoreTinymceBundle::class => ['all' => true], + ]; + ``` + +3. Update Twig templates and configuration files to use Quill options instead + of TinyMCE-specific settings. See [Configuration](./02_Configuration.md) for + toolbar options and global defaults. + +## Known Incompatibilities + +### Tables and Lists + +Quill renders TinyMCE tables and lists differently. +Check all WYSIWYG fields that contain tables or lists after migration.