.. include:: /Includes.rst.txt .. _introduction: ============ Introduction ============ The RTE CKEditor Image extension provides comprehensive image handling capabilities for |typo3|'s CKEditor Rich Text Editor. This extension enables editors to insert, configure, and style images directly within the CKEditor interface, with full integration into |typo3|'s File Abstraction Layer (FAL). Key Features ============ .. card-grid:: :columns: 1 :columns-md: 2 :gap: 4 :card-height: 100 .. card:: CKEditor 5 Integration Native CKEditor 5 plugin with full toolbar integration and TYPO3 file browser support. .. card-footer:: :ref:`Plugin Development ` :button-style: btn btn-secondary stretched-link .. card:: TYPO3 FAL Support Full File Abstraction Layer integration with file references, metadata, and browser. .. card-footer:: :ref:`RTE Setup ` :button-style: btn btn-secondary stretched-link .. card:: Image Processing Magic images, cropping, scaling with configurable quality multipliers (1x-6x). .. card-footer:: :ref:`Configuration ` :button-style: btn btn-secondary stretched-link .. card:: Custom Styles Define custom image styles (borders, shadows, alignment) via YAML configuration. .. card-footer:: :ref:`Image Styles ` :button-style: btn btn-secondary stretched-link .. card:: Responsive Images Automatic srcset generation and picture element support for responsive layouts. .. card-footer:: :ref:`Responsive Examples ` :button-style: btn btn-secondary stretched-link .. card:: Performance Native lazy loading, intersection observer fallback, and optimized rendering. .. card-footer:: :ref:`Advanced Features ` :button-style: btn btn-secondary stretched-link .. card:: Event Architecture PSR-14 event dispatching for custom image processing and rendering hooks. .. card-footer:: :ref:`Event Listeners ` :button-style: btn btn-secondary stretched-link .. card:: Security Protocol blocking, XSS prevention, file validation, and FAL-based access control. .. card-footer:: :ref:`Security Guide ` :button-style: btn btn-secondary stretched-link .. card:: Quality Multipliers .. versionadded:: 13.1.5 Retina (2x), Ultra (3x), and Print (6x) quality settings for high-DPI displays. .. card-footer:: :ref:`Quality Settings ` :button-style: btn btn-secondary stretched-link .. card:: noScale Mode .. versionadded:: 13.1.5 Skip image processing entirely for pre-optimized images (SVG, WebP, optimized PNG). .. card-footer:: :ref:`Image Processing ` :button-style: btn btn-secondary stretched-link .. card:: Service Architecture .. versionadded:: 13.1.5 Modern Parser → Resolver → Renderer pipeline with dependency injection. .. card-footer:: :ref:`Services API ` :button-style: btn btn-secondary stretched-link .. card:: Fluid Templates .. versionadded:: 13.1.5 Customizable output via template overrides for complete rendering control. .. card-footer:: :ref:`Template Overrides ` :button-style: btn btn-secondary stretched-link .. card:: Linked Images .. versionadded:: 13.5.0 Full link support with TYPO3 link browser integration, target options, and URL parameters. .. card-footer:: :ref:`Linked Images ` :button-style: btn btn-secondary stretched-link .. card:: Figure & Caption Support Native ``
``/``
`` output. Add captions directly in the image dialog -- no custom content elements needed. .. card-footer:: :ref:`Advanced Features ` :button-style: btn btn-secondary stretched-link .. card:: Caption Width Constraint .. versionadded:: 13.6.0 Figcaptions automatically constrained to image width via ``max-width`` on ``
``. .. card-footer:: :ref:`Image Styles ` :button-style: btn btn-secondary stretched-link .. card:: Image Validation .. versionadded:: 13.5.0 CLI command and upgrade wizard to detect and fix broken image references and nested links. .. card-footer:: :ref:`Validation ` :button-style: btn btn-secondary stretched-link .. card:: TYPO3 v14 & PHP 8.5 .. versionadded:: 13.2.0 Full compatibility with TYPO3 v14 and tested with PHP 8.5. .. card-footer:: :ref:`Requirements ` :button-style: btn btn-secondary stretched-link .. admonition:: Why does this extension exist? TYPO3 **intentionally removed** RTE image handling in v10.0, recommending structured content (FAL relations) instead. This extension provides inline image support for projects that need it -- legacy migrations, editorial workflows, or content tightly coupled to surrounding text. :ref:`Read the full background and decision guide ` Visual Preview ============== .. figure:: /Images/backend-rte-editor.png :alt: Rich Text Editor with image support in TYPO3 backend :class: with-shadow :width: 600px The RTE with image support enabled, showing an inserted image with styling options .. figure:: /Images/demo.gif :alt: RTE CKEditor Image extension demo :class: with-shadow Image insertion and configuration workflow in CKEditor with TYPO3 file browser integration Version Information =================== :Supported TYPO3: 13.4.21+ LTS, 14.3+ LTS :License: AGPL-3.0-or-later :Repository: `github.com/netresearch/t3x-rte_ckeditor_image `__ :Maintainer: `Netresearch DTT GmbH `__ .. _requirements: ============ Requirements ============ System Requirements =================== - **TYPO3:** 13.4.21+ LTS or 14.3+ LTS - **PHP:** 8.2 or later - **Extensions:** cms-rte-ckeditor (included in TYPO3 core) .. note:: The plugin automatically integrates with CKEditor's ``GeneralHtmlSupport`` for style functionality. No additional configuration required. .. _quick-start: =========== Quick Start =========== Installation ============ Install via Composer: .. code-block:: bash composer require netresearch/rte-ckeditor-image .. figure:: /Images/backend-extensions-list.png :alt: Extension Manager showing RTE CKEditor Image extension installed :class: with-shadow :width: 600px The extension appears in the TYPO3 Extension Manager after installation .. versionchanged:: 13.5.0 The RTE preset and frontend TypoScript are now provided via Site Set only. You must enable the Site Set in your site configuration. **Step 1: Enable Site Set (Required)** Add the extension to your site dependencies: .. code-block:: yaml :caption: config/sites//config.yaml dependencies: - netresearch/rte-ckeditor-image This enables: - ✅ **Backend RTE**: Registers the ``rteWithImages`` preset with ``insertimage`` button - ✅ **Frontend rendering**: Includes TypoScript for image processing **Step 2: Clear Caches** .. code-block:: bash vendor/bin/typo3 cache:flush .. tip:: **Default image maxWidth** The extension's Site Set configures ``maxWidth = 1920`` for magic images. If you have **not** enabled the Site Set (e.g., when using sys_template records), TYPO3's built-in default of **300px** applies, which causes images to appear unexpectedly small. In that case, add this to your Page TSConfig: .. code-block:: typoscript RTE.default.buttons.image.options.magic { maxWidth = 1920 maxHeight = 9999 } See :ref:`integration-configuration-tsconfig` for full details. .. note:: **Using Bootstrap Package or other theme extensions?** If your site uses ``bootstrap_package`` or another theme extension with Site Sets, list this extension **after** them in your dependencies to override their RTE preset. See :ref:`troubleshooting-installation-issues` for details. .. figure:: /Images/backend-rte-with-image-button.png :alt: CKEditor toolbar with image insert button highlighted :class: with-shadow :width: 600px The ``insertimage`` button in the CKEditor toolbar opens the TYPO3 file browser for image selection Custom Configuration (Optional) ================================ If you need to customize the RTE configuration or create your own preset, see the :ref:`RTE Setup Guide ` for detailed instructions. The extension provides a default preset that you can extend or override as needed. .. important:: **Before using this extension**, please read :ref:`TYPO3 Core Removal & Design Decision ` to understand why TYPO3 intentionally removed this functionality and whether this extension is the right choice for your project.