README

Image support for CKEditor for TYPO3

Version 13.0.x for TYPO3 13.4+ License: AGPL-3.0-or-later

This extension adds comprehensive image handling capabilities to CKEditor for TYPO3.
Add issues or explore the project on GitHub.

Features

• TYPO3 FAL Integration: Native file browser with full File Abstraction Layer support
• Magic Images: Same image processing as rtehtmlarea (cropping, scaling, TSConfig supported)
• Image Dialog: Configure width, height, alt, and title (aspect ratio automatically maintained)
• Custom Styles: Configurable image styles with CKEditor 5 style system
• Lazy Loading: TYPO3 native browser lazyload support
• Event-Driven: PSR-14 events for extensibility

Requirements

• TYPO3: 13.4 or later
• PHP: 8.2, 8.3, or 8.4
• Extensions: cms-rte-ckeditor (included in TYPO3 core)

Critical Dependencies (v13.0.0+)

The CKEditor plugin requires these dependencies for style functionality:

# In your RTE YAML configuration
importModules:
  - '@ckeditor/ckeditor5-html-support'

Important: Missing GeneralHtmlSupport will disable the style dropdown for images. See Documentation for details.

Installation

1. Install the extension

   1. with composer from packagist

      composer req netresearch/rte-ckeditor-image

2. Add a preset for rte_ckeditor or override the default one (as below):

   <?php
   // EXT:my_ext/ext_localconf.php`
   $GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:my_ext/Configuration/RTE/Default.yaml';

   # EXT:my_ext/Configuration/RTE/Default.yaml
   imports:
     # Import default RTE config (for example)
     - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
     # Import the image plugin configuration
     - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }
   
   editor:
     config:
       toolbar:
         items:
           - heading
           - '|'
           - typo3image
           - link
           - '|'
           - bold
           - italic

3. Enable RTE config preset (e.g. default)

   # Page TSConfig
   RTE.default.preset = default
   

4. Include extension Static Template file

   1. go to Template » Info/Modify » Edit whole template record » Includes
   2. choose CKEditor Image Support for Include static (from extensions) before the Fluid Styled content

Configuration

(optional) Configure the Extension Configuration for this extension:

fetchExternalImages: By default, if an img source is an external URL, this image will be fetched and uploaded to the current BE users uploads folder. The default behaviour can be turned off with this option.

Maximum width/height

The maximum dimensions relate to the configuration for magic images which have to be set in Page TSConfig:

# Page TSConfig
RTE.default.buttons.image.options.magic {
    # Default: 300
    maxWidth = 1020
    # Default: 1000
    maxHeight = 800
}

Current versions of TYPO3 won't render TSConfig settings correctly out of custom template extensions (see the corresponding T3 bug: https://forge.typo3.org/issues/87068). In this case just add the settings to root page config.

Usage as lightbox with fluid_styled_content

# Template Constants
styles.content.textmedia.linkWrap.lightboxEnabled = 1

Configure a default css class for every image

# TS Setup

lib.parseFunc_RTE {
    // default class for images in bodytext:
    nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib.class {
      default = my-custom-class
    }
}

Image lazyload support

The extension supports TYPO3 lazyload handling (fluid_styled_content) for native browser lazyload.

# Template Constants type=options[lazy,eager,auto]
styles.content.image.lazyLoading = lazy

Allowed extensions

By default, the extensions from $TYPO3_CONF_VARS['GFX']['imagefile_ext'] are allowed. However, you can override this for CKEditor by adding the following to your YAML configuration:

editor:
  externalPlugins:
      typo3image:
        allowedExtensions: "jpg,jpeg,png"

Documentation

For comprehensive documentation, see Documentation/Index.md:

• Integrators: Configuration Guide | Examples | Troubleshooting
• PHP Developers: Architecture Overview | API Reference | AGENTS.md
• JS Developers: CKEditor Plugin | Style Integration | Resources/AGENTS.md
• Contributors: CONTRIBUTING.md | AGENTS.md | Tests/AGENTS.md

Development

# Quick start
composer install
make help                    # See all available targets

# Development workflow
make lint                    # Run all linters
make format                  # Fix code style
make test                    # Run tests
make ci                      # Full CI check (pre-commit)

See AGENTS.md for complete development guide, code standards, and PR checklist.

Deployment

• Developed on GitHub
• Composer repository
• TYPO3 Extension Repository
• New versions automatically uploaded to TER via GitHub Action when creating a release