netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem

13.0.0 2025-01-08 15:23 UTC

Requires

• ext-dom: *
• ext-libxml: *
• typo3/cms-backend: ^13.4
• typo3/cms-core: ^13.4
• typo3/cms-extbase: ^13.4
• typo3/cms-frontend: ^13.4
• typo3/cms-rte-ckeditor: ^13.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.61
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• squizlabs/php_codesniffer: ^3.7
• typo3/testing-framework: ^9.0

AGPL-3.0-or-later

README

Image support for CKEditor for TYPO3

This extension adds the TYPO3 image browser to CKEditor.
Add issues or explore the project on GitHub.

• Same image handling as rtehtmlarea (magic images, usual RTE TSConfig supported)
• Image browser as usual in e.g. FAL file selector
• Dialog for changing width, height, alt and title (aspect ratio automatically maintained)

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:
       # RTE default config removes image plugin - restore it:
       removePlugins: null
       toolbar:
         items:
           - '|'
           - insertImage

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"

Deployment

• developed on GitHub
• composer repository
• new version will automatically be uploaded to TER via Github Action when creating a new Github release