What does it do?

The extension rte_ckeditor provides a rich text editor (RTE) by integrating CKEditor 5 into TYPO3.

This makes it possible to use the features of CKEditor when editing rich text fields in the TYPO3 backend or frontend (if frontend editing is used). Rich text fields are fields which may contain text with markup, for example for adding a style such as bold, using lists or enumerations, headlines or adding links.

CKEditor is a WYSIWYG editor mostly written in JavaScript, and is used in many systems due to its flexibility. There are hundreds of free open-source plugins for CKEditor to enhance the editing experience.

History

Before TYPO3 v8, a custom fork of "HtmlArea", another open-source WYSIWYG editor was shipped with TYPO3 Core in a separate extension rtehtmlarea. "HtmlArea" isn't supported anymore since TYPO3 v9 LTS. You have to migrate to rte_ckeditor when upgrading from previous TYPO3 versions (=< v8).

CKEditor 4 was officially integrated as the default rich text editor in TYPO3 v8 LTS, within an extension called rte_ckeditor.

With TYPO3 v12, CKEditor 4 has been updated to CKEditor 5.

Features

The extension rte_ckeditor incorporates the features of CKEditor and adds additional functionality, configuration presets and plugins.

Some examples of features:

• Configurable via YAML files
• Configuration presets (minimal, default, full) for TYPO3
• Toolbar customization
• Link functionality: integration with TYPO3 link wizard
• Wordcount: plugin that counts and shows the chars/words/paragraphs in the footer of the editor. It also supports limiting the max. amount of chars/words.

User interfaces

CKEditor has multiple user interfaces, of which TYPO3 uses the following:

Classic

Editing is done within a fixed container. It is possible to customize how the editor behaves and how the content is styled.

Used in the TYPO3 Backend.

Inline

All formatting styles are reused from the surrounding HTML and CSS styles, allowing for a seamless frontend editing.

Used by TYPO3’s frontend_editing, which can be found on GitHub. frontend_editing is not covered in this document.

For a demonstration of all user interfaces, see the CKEditor demo.

Installation with Composer

Check whether you are already using the extension with:

composer show | grep rte

This should either give you no result or something similar to:

typo3/cms-rte-ckeditor       v12.4.11

If it is not installed yet, use the composer require command to install the extension:

composer require typo3/cms-rte-ckeditor

The given version depends on the version of the TYPO3 Core you are using.

Installation without Composer

In an installation without Composer, the extension is already shipped but might not be activated yet. Activate it as follows:

1. In the backend, navigate to the Admin Tools > Extensions module.
2. Click the Activate icon for the RTE CKEditor extension.

View Existing Configuration

To familiarize yourself with the configuration, look at the existing configuration in your TYPO3 website:

To view the existing RTE presets in the "Global Configuration", go to System > Configuration in the backend, choose $GLOBALS['TYPO3_CONF_VARS'] (Global Configuration) and select RTE:

By default, TYPO3 is shipped with three configuration presets:

• default
• full
• minimal

Minimal Example

Here is a very minimal example of changing the default configuration. All configuration is done in a custom sitepackage extension, see also Use a Sitepackage extension.

Override the configuration preset "default" by adding this in <my_extension>/ext_localconf.php (replace my_extension with your extension key):

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:my_extension/Configuration/RTE/Default.yaml';

Add the file Configuration/RTE/Default.yaml to your extension, use the file EXT:rte_ckeditor/Configuration/RTE/Full.yaml (GitHub) as example.

We explain the example Minimal.yaml from the Core:

# Load default processing options
imports:
  - { resource: 'EXT:rte_ckeditor/Configuration/RTE/Processing.yaml' }
  - { resource: 'EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml' }

# Minimal configuration for the editor
editor:
  config:
    toolbar:
      items:
        - bold
        - italic
        - '|'
        - clipboard
        - undo
        - redo

line #2

Imports existing files to make basic parts reusable and improve structure of configuration

line #9 toolbar

See toolbar

Page TSconfig

We recommend you to put all configurations for the preset in the YAML configuration. However, it is still possible to override these settings through the page TSconfig.

You can find a list of configuration properties in the Page TSconfig reference, chapter RTE.

Global Configuration

Global Configuration is a system-wide general configuration.

if (empty($GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['myCustomPreset'])) {
    $GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['myCustomPreset']
        = 'EXT:<extkey>/Configuration/RTE/MyCustomPreset.yaml';
}

How to view settings

You can view the Global Configuration in System > Configuration > $GLOBAL['TYPO3_CONF_VARS'] (Global Configuration) > RTE.

YAML

Most of the configuration of rte_ckeditor will be done in a YAML file.

CKEditor related TCA configuration

The table configuration array is used to configure database fields and how they will behave in the backend when edited. It is for example used to define that tt_content.bodytext should be edited with a rich text editor.

How to view settings

You can view TCA in the backend: System > Configuration > $GLOBAL['TCA'] (Table configuration array).

For example, look at tt_content > columns > bodytext.

However, you will find that neither enableRichtext, nor richtextConfiguration is set here. They are configured in tt_content > types for various content types, for example look at tt_content > types > text > columnsOverrides.

Configuration Overview

The main principles of configuring a Rich Text Editor in TYPO3 apply to editing with any Rich Text Editor (rte_ckeditor, ...).

Some of the functionality (for example the RTE transformations) is embedded in the TYPO3 core and not specific to rte_ckeditor.

There are three main parts relevant for rich text editing with TYPO3:

Editor configuration

This covers how the actual editor (in this case CKEditor) should behave, what buttons should be shown, what options are available.

RTE transformations

This defines how the information is processed when saved from the Rich Text Editor to the database. And when loaded from the database into the Rich Text Editor.

Frontend output configuration

The information fetched from the database may need to be processed for the frontend. The configuration of the frontend output is configured via TypoScript.

This section mainly covers editor configuration and RTE transformations, as for TypoScript the TypoScript reference handles output of HTML content and has everything preset (see parseFunc).

Editor Configuration

key1: value
key2: value

key1:
  key1-2: value

- list item 1
- list item 2

key:
  key2:
    - item 1
    - item 2

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default']
    = 'EXT:rte_ckeditor/Configuration/RTE/Default.yaml';

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default']
    = 'EXT:my_extension/Configuration/RTE/Default.yaml';

'content' => [
    'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.text',
    'config' => [
        'type' => 'text',
        'cols' => 48,
        'rows' => 5,
        'enableRichtext' => true,
        'richtextConfiguration' => 'default',
    ],
],

# per-field
RTE.config.tt_content.bodytext.preset = minimal

# per-type
RTE.config.tt_content.bodytext.types.bullets.preset = bullets

# Restrict format_tags to h2 in bodytext field of content elements
RTE.config.tt_content.bodytext.editor.config.format_tags = h2

RTE Transformations

Transformations are directives for parsing HTML markup. They are executed by the TYPO3 Core every time a RTE-based field is saved to the TYPO3 database or fetched from the database for the Rich Text Editor to render. This way, there are always two ways / two transformations applied.

There are several advantages for transformations, the most prominent reason is to not inject bad HTML code into the database which in turn would be used for output. Transformations from the RTE towards the database can filter out HTML tags or attributes.

You can read more about RTE Transformations in TYPO3 Explained.

Frontend Output Configuration

Mostly due to historical reasons, the frontend output added <p> tags to each line which is not wrapped in HTML. Additionally the <typolink> tag was replaced by <a> tags and checked if e.g. if a link was set to a specific page within TYPO3 is actually accessible for this specific visitor.

The latter part is still necessary, so the <a href="t3://page?id23"> HTML snippet is replaced by a speaking URL which the power of typolink will still take care of. There are, of course, more options to it, like default “target” attributes for external links or spam-protecting links to email addresses, which all happens within the typolink logic, the master for generating a link in the TYPO3 Frontend rendering process.

lib.parseFunc.tags {
  a = TEXT
  a {
    current = 1
    typolink {
      parameter.data = parameters:href
      title.data = parameters:title
      ATagParams.data = parameters:allParams
      target.data = parameters:target
      extTarget = {$styles.content.links.extTarget}
      extTarget.override.data = parameters:target
    }
  }
}

Use a Sitepackage extension

It is generally recommended to use a sitepackage extension to customize a TYPO3 website. The sitepackage contains configuration files for that site.

See the TYPO3 Sitepackage Tutorial on how to create a sitepackage. We assume here your sitepackage extension has the key my_sitepackage.

The YAML preset files should be kept in folder EXT:my_sitepackage/Configuration/RTE/.

RTE configurations need to be registered in your sitepackages ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['myconfig']
    = 'EXT:my_sitepackage/Configuration/RTE/MyConfiguration.yaml';

Use TYPO3’s Core Default.yaml as boilerplate

It is recommended to start by copying the file typo3/sysext/rte_ckeditor/Configuration/RTE/Default.yaml into your sitepackage to the file EXT:my_sitepackage/Configuration/RTE/MyConfiguration.yaml.

Check TYPO3's Core Full.yaml to gain insight into a more extensive configuration

This preset shows more configured options and plugins. It is not intended for real use. It acts as an example.

typo3/sysext/rte_ckeditor/Configuration/RTE/Full.yaml

Use Core includes

It is recommended to use the following includes at the top of your custom configuration:

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Processing.yaml" }
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml" }
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml" }

If you started out by copying this extensions Default.yaml as boilerplate the imports should already be there.

The include files are already split up so the processing transformations can just be included or even completely disabled (by removing the line for importing).

Please be aware that removing the Processing.yaml removes security measures. In that case you have to take care of keeping the ckeditor safe yourself.

How do I use a different preset?

Instead of using the default "default" preset, you can change this, for example to "full", using page TSconfig:

RTE.default.preset = full

Of course, the preset must already exist, or you must define it. rte_ckeditor ships with presets "minimal", "default" and "full".

Additionally, you can set specific presets for specific types of textfields.

For example to use preset "full" for the field "bodytext" of all content elements:

RTE.config.tt_content.bodytext.preset = full

To use preset "minimal" for the field "bodytext" of only content elements with ctype="text":

RTE.config.tt_content.bodytext.types.text.preset = minimal

For more examples, see RTE in "TSconfig Reference".

How do I create my own preset?

In your sitepackage extension:

In ext_localconf.php, replace my_extension with your extension key, replace my_preset and MyPreset.yaml with the name of your preset.

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['my_preset']
    = 'EXT:my_extension/Configuration/RTE/MyPreset.yaml';

In Configuration/RTE/MyPreset.yaml, create your configuration, for example:

# Import basic configuration
imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Processing.yaml" }
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml" }
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml" }
# Add configuration for the editor
# For complete documentation see http://docs.ckeditor.com/#!/api/CKEDITOR.config
editor:
  config:
    # Include custom CSS
    contentsCss:
      - "EXT:my_extension/Resources/Public/Css/rte.css"

See also the note for editor.config.contentsCss.

How do I customize the toolbar?

The toolbar can be customized individually by configuring required toolbar items in the YAML configuration. The following configuration shows the toolbar configuration of the minimal editor setup included in file EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml:

# Minimal configuration for the editor
editor:
  config:
    toolbar:
      items:
        - bold
        - italic
        - '|'
        - clipboard
        - undo
        - redo

The '|' can be used as a separator between groups of toolbar items.

Additional configuration options are available in the official CKEditor 5 Toolbar documentation

# Minimal configuration for the editor
editor:
  config:
    toolbar:
      items:
        - bold
        - italic
        - { label: 'Additional', icon: 'threeVerticalDots', items: [ 'specialCharacters', 'horizontalLine' ] }

How do I allow a specific tag?

Allowed content in CKEditor5 is to be configured via the General HTML Support plugin option config.htmlSupport.

# Allow the <iframe> tag with all attributes, all classes and all styles,
# as well as demonstrating class restrictions to the <i> tag
editor:
  config:
    htmlSupport:
      allow:
        - { name: 'iframe', attributes: true, classes: true, styles: true }
        # multiple definitions for the same tag name are possible
        - { name: 'i', classes: [ 'fa-brands', 'fa-typo3' ] }
        # allows any repetitive class name, that starts with `fa-`
        # (the regular expression has to be defined in `pattern`)
        - { name: 'i', classes: { pattern: '^((fa-[^\h]+)(\h+|$))+' } }

How do I configure the font plugin?

In order to use the font plugin, the RTE configuration needs to be adapted:

editor:
  config:
    toolbar:
      items:
        # add button to select font family
        - fontFamily
        # add button to select font size
        - fontSize
        # add button to select font color
        - fontColor
        # add button to select font background color
        - fontBackgroundColor

    fontColor:
      colors:
        - { label: 'Orange', color: '#ff8700' }
        - { label: 'Blue', color: '#0080c9' }
        - { label: 'Green', color: '#209d44' }

    fontBackgroundColor:
      colors:
        - { label: 'Stage orange light', color: '#fab85c' }

    fontFamily:
      options:
        - 'default'
        - 'Arial, sans-serif'

    fontSize:
      options:
        - 'default'
        - 18
        - 21

    importModules:
      - { 'module': '@ckeditor/ckeditor5-font', 'exports': [ 'Font' ] }

More information can be found in the official documentation of CKEditor.

How do I configure the Link Browser?

The TYPO3 Link Browser can be utilized in both the RTE and for FormEngine TCA fields. The latter is configured through TCA settings, and the RTE editor itself is configured via the central YAML file.

There are several configuration options available. Please see Link Browser specific options for the detailed reference, and EXT:rte_ckeditor/Configuration/RTE/Editor/LinkBrowser.yaml (GitHub) for an example configuration.

How do I create a custom plugin?

With CKEditor 5 the plugin architecture has changed and CKEditor 4 plugins are not compatible with CKEditor 5. It is advised to read the CKEditor 4 to 5 migration to understand the conceptual changes, also related to plugins.

Writing a custom plugin for CKEditor 5 can be done in TypeScript or JavaScript, using the CKEditor5 plugin system.

In this example, we integrate a simple timestamp plugin to CKEditor 5. Make sure to replace <my_extension> with your extension key.

1. Create the plugin file

   Add the following ES6 JavaScript code:

   EXT:<my_extension>/Resources/Public/JavaScript/Ckeditor/timestamp-plugin.js

   import { Plugin } from '@ckeditor/ckeditor5-core';
   import { ButtonView } from '@ckeditor/ckeditor5-ui';
   
   export class Timestamp extends Plugin {
     static pluginName = 'Timestamp';
   
     init() {
       const editor = this.editor;
   
       // The button must be registered among the UI components of the editor
       // to be displayed in the toolbar.
       editor.ui.componentFactory.add(Timestamp.pluginName, () => {
         // The button will be an instance of ButtonView.
         const button = new ButtonView();
   
         button.set({
           label: 'Timestamp',
           withText: true
         });
   
         // Execute a callback function when the button is clicked
         button.on('execute', () => {
           const now = new Date();
   
           // Change the model using the model writer
           editor.model.change(writer => {
   
             // Insert the text at the user's current position
             editor.model.insertContent(writer.createText(now.toString()));
           });
         });
   
         return button;
       });
     }
   }

   Copied!

2. Register the ES6 JavaScript

   EXT:<my_extension>/Configuration/JavaScriptModules.php

   <?php
   
   return [
       'dependencies' => ['backend'],
       'tags' => [
           'backend.form',
       ],
       'imports' => [
           '@my-vendor/my-package/timestamp-plugin.js' => 'EXT:my_extension/Resources/Public/JavaScript/Ckeditor/timestamp-plugin.js',
       ],
   ];
   

   Copied!

3. Include the plugin in the CKEditor configuration

   EXT:<my_extension>/Configuration/RTE/MyPreset.yaml

   editor:
     config:
       importModules:
         - { module: '@my-vendor/my-package/timestamp-plugin.js', exports: [ 'Timestamp' ] }
       toolbar:
         items:
           - bold
           - italic
           - '|'
           - clipboard
           - undo
           - redo
           - '|'
           - timestamp
   

   Copied!

   The importModules item in line 4 imports the previously registered ES6

   module. The timestamp item in line 14 adds the plugin to the toolbar.

4. Use the plugin

   

YAML Configuration Reference

When configuring the CKEditor using YAML, these are the property names that are currently used:

allowedOptions: 'target,title,class,params,rel'

allowedOptions: ''

allowedTypes: 'page,url,file,folder,email,customType'

allowedTypes: ''

classesAnchor:
  - { class: "customPageCssClass", type: "page", target: "" }
  - { class: "customUrlCssClass", type: "url", target: "_blank" }
  - { class: "customFileCssClass", type: "file", target: "_parent" }
  - { class: "customFolderCssClass", type: "folder" }
  - { class: "customTelephoneCssClass", type: "telephone" }
  - { class: "customEmailCssClass", type: "email" }

buttons:
  link:
    options:
      removeItems: 'telephone'

buttons:
  link:
    relAttribute:
      enabled: true

buttons:
  link:
    queryParametersSelector:
      enabled: true

buttons:
  link:
    targetSelector:
      disabled: true

buttons:
  link:
    properties:
      class:
        required: true

buttons:
  link:
    properties:
      class:
        allowedClasses: 'globalCss1,globalCss1,CustomPageCssClass'

buttons:
  link:
    telephone:
      class:
        default: "customTelephoneCssClass"
    email:
      class:
        default: "customEmailCssClass"

classes:
  globalCss1:
    name: "A Label for globalCss1"
    value: "color: red"
  customEmailCssClass:
    name: "An email-specific class for VIPs"

Page TSconfig

We recommend you to put all configurations for the preset in the YAML configuration. However, it is still possible to override these settings through the page TSconfig.

You can find a list of configuration properties in the Page TSconfig reference, chapter RTE.

Example: Use bold

Select text and click on the B (for bold) button:

Example: Create a link

Select text and click on the Link button: