Rich text editor in the frontend form 

Requirements for the frontend rich text editor 

• The event form based on EXT:form (site setting events2.form.useExtForm).
• The system extension EXT:rte_ckeditor ( typo3/cms-rte-ckeditor ). The editor is not activated if it is not installed.

No build step (npm, webpack) is needed. The CKEditor 5 ES modules, translations and styles shipped with EXT:rte_ckeditor are used.

Site settings of the frontend rich text editor 

The following settings are provided by the site set jweiland/events2 and are available in TypoScript as plugin.tx_events2.settings.new.richText, see richText.enable.

Enable the frontend rich text editor 

Enable the site setting events2.form.richText.enable of the site set jweiland/events2.

That is all for the description: the element detail-description is the default of the site setting events2.form.richText.elements. This works for overridden copies of NewEvent.form.yaml as well, as long as they use this identifier.

events2:
  form:
    richText:
      enable: true

Rich text elements of the event form 

An element of the form is a rich text element if

• its identifier is listed in the site setting events2.form.richText.elements or
• it has dataType: richText in its dbMapping.

If the editor is enabled, events2 configures each rich text element automatically:

• The dataType of the element is richText, so the edit form gets the stored HTML instead of plain text.
• The mapping of the element in the SaveEventFinisher gets sanitizeRichText: true (instead of convertPlainTextToHtml or normalizePlainText).
• While rendering, the textarea gets the attribute data-events2-rich-text with the options of the editor, including the allowed tags of its column (see Toolbar of the frontend rich text editor). The assets are only loaded on pages of the form which contain a rich text element. Each textarea gets its own editor.

If the editor is disabled, rich text elements fall back to plain text: dataType: plainText and convertPlainTextToHtml instead of sanitizeRichText.

The editor of an element is configured for the column properties.dbMapping.column of the table properties.dbMapping.table. The table is optional and defaults to tx_events2_domain_model_event. Set it only for elements which are stored in another table, so the toolbar matches the allowed tags of that column. Use the same table as the mapping of the element in the SaveEventFinisher:

- label: 'Notes of the organizer'
  type: Textarea
  identifier: organizer-notes
  properties:
    dbMapping:
      table: tx_events2_domain_model_organizer
      column: tx_myext_notes
      dataType: richText

- label: 'Program'
  type: Textarea
  identifier: program
  properties:
    dbMapping:
      column: tx_myext_program
      # Optional: Instead of listing "program" in the site setting
      dataType: richText

finishers:
  1:
    identifier: SaveEventFinisher
    options:
      4:
        table: tx_events2_domain_model_event
        elements:
          program:
            mapOnDatabaseColumn: tx_myext_program

events2:
  form:
    richText:
      enable: true
      elements: 'detail-description, program'

Loaded files of the frontend rich text editor 

The import map of the CKEditor modules is defined in EXT:events2/Configuration/JavaScriptModules.php and rendered by the PageRenderer of TYPO3 (<script type="importmap">, respecting the Content Security Policy of the site). The ES module EXT:events2/Resources/Public/JavaScript/rich-text-editor.js creates an editor for each textarea with the attribute data-events2-rich-text. It loads the UI translation of the current site language. The style sheets EXT:rte_ckeditor/Resources/Public/Css/editor.css and EXT:events2/Resources/Public/Css/RichTextEditor.css are added with the AssetCollector.

The files are about 1.6 MB uncompressed and about 400 KB compressed with gzip.

Toolbar of the frontend rich text editor 

The toolbar is built from the tags which are allowed for the column of the element (see Allowed markup of the frontend rich text editor). With the default configuration, it contains:

• Heading: Paragraph, Heading 2, Heading 3 (Heading 1 is used for the title of the event)
• Bold, Italic
• Bulleted list, numbered list
• Link with the protocols http, https, mailto and tel and the option Open in a new tab
• Undo, Redo

The editor gets one heading option for each allowed element of <h1> to <h6>. The titles of the headings are translated by CKEditor. The heading dropdown is only shown if at least one heading is allowed. The toolbar items are only shown if their element is allowed:

• Bold: <strong>
• Italic: <em>
• Bulleted list: <ul>
• Numbered list: <ol>
• Link: <a>

Undo and Redo are always available. Allowed elements without a toolbar item, like <u> or <blockquote>, are kept when the value is saved, but can not be selected in the editor.

Toolbar items which do not fit into the width of the form are grouped into a dropdown. The toolbar can be focused with Alt + F10.

Allowed markup of the frontend rich text editor 

The submitted HTML is sanitized on the server with typo3/html-sanitizer , as a request can bypass the editor. By default, only these tags are allowed:

• <p>, <br>, <strong>, <em>, <h2>, <h3>, <ul>, <ol>, <li>
• <a> with href (http, https, mailto, tel) and target="_blank", which gets rel="noopener noreferrer"

<b> is converted to <strong>, <i> to <em> and <h1>, <h4>, <h5>, <h6> to <p>. All attributes like class, style or on* are removed. Links with other protocols like javascript: or data: are removed, their text is kept. <script>, <style>, <iframe>, images, forms and similar elements are removed including their content. The text of all other elements is kept. Other block elements like <div>, <blockquote> or table cells become paragraphs. Text and inline formatting outside of blocks is wrapped into a paragraph like the editor does, so <strong>, <em> and links are kept.

The tags can be modified with the PSR-14 event ModifyRichTextSanitizerConfigurationEvent, see Modify the allowed markup of the frontend rich text editor.

Modify the allowed markup of the frontend rich text editor 

The PSR-14 event JWeilandEvents2EventModifyRichTextSanitizerConfigurationEvent is dispatched for each rich text element:

• While rendering the form element, to build the headings and toolbar items of the editor (see Toolbar of the frontend rich text editor). Table and column are taken from properties.dbMapping.table (default: tx_events2_domain_model_event) and properties.dbMapping.column of the form element.
• Each time a submitted value which contains HTML is sanitized. Values without any tag are converted like plain text and do not dispatch the event.

The event receives the defaults, which are defined as constants in JWeilandEvents2SanitizerVisitorRichTextVisitor. So one listener configures both the editor and the sanitizing on the server.

<?php

declare(strict_types=1);

namespace MyVendor\MySitepackage\EventListener;

use JWeiland\Events2\Event\ModifyRichTextSanitizerConfigurationEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(identifier: 'my-sitepackage/allow-heading-4')]
final class AllowHeading4EventListener
{
    public function __invoke(ModifyRichTextSanitizerConfigurationEvent $event): void
    {
        if ($event->getTable() !== 'tx_events2_domain_model_event'
            || $event->getColumn() !== 'detail_information'
        ) {
            return;
        }

        // Keep <h4> instead of converting it to <p>
        $event->setAllowedTags([...$event->getAllowedTags(), 'h4']);
    }
}

Frontend form without JavaScript 

Without JavaScript, the plain textarea is shown. For new events, plain text can be entered as before. When editing an event, the textarea contains the stored HTML. Values without any tag are converted like the plain text description.