Advanced Configuration

Advanced configuration options including custom styles, performance optimization, extension settings, and best practices.

Note

For Advanced Users

The extension works out-of-the-box with zero configuration. This section covers:

Custom image styles and style groups
Performance optimization and image processing
Extension-specific settings
Best practices for production environments

You only need these configurations if you want to customize beyond the automatic defaults.

Table of Contents

CKEditor Style Configuration

Adding Image Styles

Define custom styles for images:

EXT:my_ext/Configuration/RTE/Default.yaml

editor:
  config:
    style:
      definitions:
        - name: 'Image Left'
          element: 'img'
          classes: ['float-left', 'mr-3']
        - name: 'Image Right'
          element: 'img'
          classes: ['float-right', 'ml-3']
        - name: 'Image Center'
          element: 'img'
          classes: ['d-block', 'mx-auto']
        - name: 'Full Width'
          element: 'img'
          classes: ['w-100']

Style Groups

Organize styles in groups:

editor:
  config:
    style:
      definitions:
        # ... style definitions ...

      # Group styles in dropdown
      groupDefinitions:
        - name: 'Image Alignment'
          styles: ['Image Left', 'Image Right', 'Image Center']
        - name: 'Image Size'
          styles: ['Full Width', 'Half Width']

Extension Configuration

Configure extension behavior in Extension Manager or settings.php:

fetchExternalImages

type: boolean
Default: true
Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image']['fetchExternalImages']

Controls whether external image URLs are automatically fetched and uploaded to the backend user's upload folder.

When enabled, pasting external image URLs into the editor will trigger automatic download and upload to FAL.

Options:

true: External image URLs are fetched and uploaded to BE user's uploads folder
false: External URLs remain as external links (not recommended for security)

Example:

settings.php or LocalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'fetchExternalImages' => true,
];

Performance Optimization

Image Processing Configuration

LocalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['GFX'] = [
    'processor' => 'ImageMagick',
    'processor_path' => '/usr/bin/',
    'processor_enabled' => true,
    'processor_effects' => true,

    // Image quality
    'jpg_quality' => 85,

    // Maximum dimensions
    'imagefile_ext' => 'gif,jpg,jpeg,png,webp',
];

Processed File Cache

TYPO3 caches processed images in _processed_/ folder. Clear if needed:

# TYPO3 CLI
./vendor/bin/typo3 cache:flush --group=pages

Performance Best Practices

Configure appropriate image processing quality (jpg_quality: 85)
Enable TYPO3 page caching for content with images
Use WebP format where supported
Implement lazy loading for images below the fold
Set reasonable maximum dimensions in TSConfig
Consider using CDN for image delivery in production

Example Configurations

Minimal Setup

Minimal RTE with just image support

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null
    toolbar:
      items: [insertimage]

Full-Featured Setup

Complete RTE with all features

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Full.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null
    toolbar:
      items:
        - heading
        - '|'
        - bold
        - italic
        - '|'
        - insertimage
        - link
        - '|'
        - bulletedList
        - numberedList
        - '|'
        - style

    style:
      definitions:
        - name: 'Image Left'
          element: 'img'
          classes: ['float-left']
        - name: 'Image Right'
          element: 'img'
          classes: ['float-right']

  externalPlugins:
    typo3image:
      allowedExtensions: "jpg,jpeg,png,gif,webp"

Page TSConfig

RTE.default {
    preset = full

    buttons.image.options.magic {
        maxWidth = 1920
        maxHeight = 1080
    }
}

TypoScript Setup

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib.class {
    default = img-fluid
}

Best Practices

Configuration Best Practices

Start with minimal configuration and add features incrementally
Test in staging environment before deploying to production
Use separate RTE presets for different content types
Enable caching for processed images
Set appropriate maxWidth/maxHeight to prevent oversized images
Configure lazy loading for better performance
Use meaningful style names that reflect intent, not appearance
Document custom configurations for team members

Security Considerations

Restrict allowed file extensions to safe image formats
Configure appropriate file mounts for backend users
Review and limit upload folder permissions
Validate image dimensions and file sizes
Keep extension and TYPO3 core up to date

Maintenance

Regularly clear processed image cache
Monitor storage usage in upload folders
Review and clean unused images periodically
Keep documentation of custom configurations
Test after TYPO3 core or extension updates

Using with Third-Party Extensions

Automatic Support for ALL Extensions (v13.x+)

This extension automatically configures RTE image support for all tables with RTE-enabled text fields, including:

TYPO3 core tables (tt_content, sys_template)
Third-party extensions (tx_news_domain_model_news, etc.)
Custom extension tables

No manual configuration is required. The extension uses a PSR-14 event listener that automatically adds the rtehtmlarea_images soft reference to all RTE fields during TCA compilation.

Extension Configuration

You can customize the automatic behavior via Extension Configuration:

Admin Tools > Settings > Extension Configuration > rte_ckeditor_image

enableAutomaticRteSoftref

type: boolean
Default: 1 (enabled)

Master switch to enable or disable automatic RTE softref processing.

When enabled, the extension automatically adds rtehtmlarea_images soft reference to all RTE-enabled text fields across all tables.

excludedTables

type: string (comma-separated)
Default: (empty)

Comma-separated list of table names to exclude from automatic processing.

Example: tx_form_formframework,sys_template

Use this if specific tables should not have automatic softref processing.

includedTablesOnly

type: string (comma-separated)
Default: (empty)

Whitelist mode: If set, ONLY these tables will be processed.

Example: tt_content,tx_news_domain_model_news,tx_myext_article

This overrides the excludedTables setting. Leave empty to process all tables (recommended).

Configuration Examples

Exclude Specific Tables:

settings.php or LocalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'enableAutomaticRteSoftref' => true,
    'excludedTables' => 'tx_form_formframework,sys_template',
];

Whitelist Mode (Only Specific Tables):

settings.php or LocalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'enableAutomaticRteSoftref' => true,
    'includedTablesOnly' => 'tt_content,tx_news_domain_model_news',
];

Disable Automatic Processing:

settings.php or LocalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'enableAutomaticRteSoftref' => false,
];

Note

After changing extension configuration, clear all caches:

./vendor/bin/typo3 cache:flush

Troubleshooting Third-Party Extension Issues

Images Disappear When Saving

Symptom: Images inserted in RTE fields disappear after saving the record.

Cause: Automatic softref processing may be disabled, or the table is excluded.

Solution:

Verify automatic processing is enabled:

// Check extension configuration
$config = $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'];
// enableAutomaticRteSoftref should be true (default)

Check if the table is excluded:

// Check excludedTables and includedTablesOnly settings
debug($config['excludedTables']);
debug($config['includedTablesOnly']);

Verify soft reference is configured in TCA:

// In TYPO3 backend console or debug output
debug($GLOBALS['TCA']['your_table']['columns']['your_field']['config']['softref']);
// Should output: "rtehtmlarea_images" or include it in comma-separated list

Check if data-htmlarea-file-uid attribute is preserved:

-- Check database content
SELECT bodytext FROM tx_news_domain_model_news WHERE uid = 123;
-- Should contain: data-htmlarea-file-uid="456"

Clear all caches and retry:
```
./vendor/bin/typo3 cache:flush
```
Copied!

Automatic Processing Not Working

Symptom: RTE images are not tracked automatically in custom tables.

Cause: Event listener not registered, caches not cleared, or configuration issue.

Solution:

Verify the event listener is registered:

# Check if RteSoftrefEnforcer class exists
ls Classes/Listener/TCA/RteSoftrefEnforcer.php

Verify Services.yaml configuration:

# Check listener registration
grep -A 5 "RteSoftrefEnforcer" Configuration/Services.yaml

Clear all caches:
```
./vendor/bin/typo3 cache:flush
```
Copied!

Check if the field is RTE-enabled:

// Field must have type='text' AND enableRichtext=true
debug($GLOBALS['TCA']['your_table']['columns']['your_field']['config']);

data-htmlarea-file-uid Attribute Missing

Symptom: Images render but the data-htmlarea-file-uid attribute is missing from saved content.

Cause: Soft reference parser not registered or not being invoked.

Solution:

Verify soft reference parser is registered:

# Check Services.yaml for softreference.parser
grep -A 3 "softreference.parser" Configuration/Services.yaml

Verify soft reference is in TCA (see "Images Disappear When Saving" above)
Clear all caches:
```
./vendor/bin/typo3 cache:flush
```
Copied!

Images Not Processed in Frontend

Symptom: Images appear as <img> tags with data-htmlarea-file-uid in frontend HTML.

Cause: TypoScript configuration missing or incorrect.

Solution: Ensure TypoScript static template is included:

# Include static template in your root template
# Template > Info/Modify > Edit whole template record > Includes
# Select: "CKEditor Image Support" for "Include static (from extensions)"

Advanced Configuration

CKEditor Style Configuration

Adding Image Styles

Style Groups

Extension Configuration

fetchExternalImages

Performance Optimization

Image Processing Configuration

Processed File Cache

Performance Best Practices

Example Configurations

Minimal Setup

Full-Featured Setup

Best Practices

Configuration Best Practices

Security Considerations

Maintenance

Using with Third-Party Extensions

Extension Configuration

enableAutomaticRteSoftref

excludedTables

includedTablesOnly

Configuration Examples

Troubleshooting Third-Party Extension Issues

Images Disappear When Saving

Automatic Processing Not Working

data-htmlarea-file-uid Attribute Missing

Images Not Processed in Frontend

Related Documentation

Configuration Topics

General Documentation