:navigation-title: Frontend rich text editor
.. include:: /Includes.rst.txt
.. _frontend-rich-text-editor:
=====================================
Rich text editor in the frontend form
=====================================
.. versionadded:: 10.0.0
Textarea elements of the company form based on EXT:form can be edited
with a CKEditor 5.
Textarea elements of the company form (see :ref:`company-form`) can be
edited with a small CKEditor 5. Frontend users can format the description
of their company, and formatting added by editors in the backend is kept
when the company is edited in the frontend. By default, the element
`description` (column `description`) gets the editor. Further elements can
be added by configuration.
The feature is disabled by default. Without it, the description is a plain
textarea. Its plain text is stored as HTML like the backend RTE stores it:
a line break becomes :html:`
`, an empty line starts a new paragraph.
When a company is edited, the stored HTML is converted back into plain
text.
.. contents::
:caption: Table of contents
:local:
.. _frontend-rich-text-editor-requirements:
Requirements for the frontend rich text editor
==============================================
* The company form based on EXT:form of the Management plugin.
* The system extension EXT:rte_ckeditor
(:composer:`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.
.. _frontend-rich-text-editor-site-settings:
Site settings of the frontend rich text editor
==============================================
The following settings are provided by the site set
`jweiland/yellowpages2` and are available in TypoScript as
:typoscript:`plugin.tx_yellowpages2.settings.new.richText`.
.. confval-menu::
:name: yellowpages2-rich-text-settings
:display: table
:type:
:default:
.. confval:: yellowpages2.form.richText.enable
:name: yellowpages2-form-richtext-enable
:type: bool
:default: `false`
Use CKEditor 5 of EXT:rte_ckeditor for the rich text elements of
the company form based on EXT:form.
.. confval:: yellowpages2.form.richText.elements
:name: yellowpages2-form-richtext-elements
:type: string
:default: `description`
Comma-separated identifiers of the form elements which get the rich
text editor. Elements with :yaml:`dataType: richText` in their
:yaml:`dbMapping` get the editor, too.
.. confval:: yellowpages2.form.richText.translationsPath
:name: yellowpages2-form-richtext-translationspath
:type: string
:default: `EXT:rte_ckeditor/Resources/Public/Contrib/translations/`
Folder with the translations of the user interface of CKEditor 5,
e.g. :file:`de.js`. The file of the language of the site is loaded.
Use a path like `EXT:my_sitepackage/Resources/Public/Ckeditor/`. The
translation of the language of the current site is loaded, if it
exists. Leave it empty to use the English user interface only. The
property :yaml:`properties.richTextEditor.translationsPath` of a form
element takes precedence.
.. _frontend-rich-text-editor-enable:
Enable the frontend rich text editor
====================================
Enable the site setting
:confval:`yellowpages2.form.richText.enable `
of the site set `jweiland/yellowpages2`.
That is all for the description: the element `description` is the
default of the site setting
:confval:`yellowpages2.form.richText.elements `.
This works for overridden copies of :file:`Company.form.yaml` as well, as
long as they use this identifier.
.. _frontend-rich-text-editor-example-description:
Example: Enable the rich text editor for the description
--------------------------------------------------------
.. code-block:: yaml
:caption: config/sites//settings.yaml
yellowpages2:
form:
richText:
enable: true
.. _frontend-rich-text-editor-elements:
Rich text elements of the company form
======================================
An element of the form is a rich text element if
* its identifier is listed in the site setting
:confval:`yellowpages2.form.richText.elements `
or
* it has :yaml:`dataType: richText` in its :yaml:`dbMapping`.
If the editor is enabled, yellowpages2 configures each rich text element
automatically:
* The :yaml:`dataType` of the element is :yaml:`richText`, so the edit
form gets the stored HTML instead of plain text.
* The mapping of the element in the `SaveCompanyFinisher` gets
:yaml:`sanitizeRichText: true` (instead of
:yaml:`convertPlainTextToHtml` or :yaml:`normalizePlainText`).
* The element is rendered with the partial
:file:`RichTextEditor/Textarea.html`
(:yaml:`renderingOptions.templateName`), which loads the assets of the
editor, see :ref:`frontend-rich-text-editor-assets`. The element gets
the property :yaml:`richTextEditor.translationsPath` of the site
setting :confval:`yellowpages2.form.richText.translationsPath
`. Values of the form definition
are kept.
* While rendering, the textarea gets the attribute
:html:`data-yellowpages2-rich-text` with the options of the editor,
including the allowed tags of its column (see
:ref:`frontend-rich-text-editor-toolbar`). 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:
:yaml:`dataType: plainText` and :yaml:`convertPlainTextToHtml` instead of
:yaml:`sanitizeRichText`.
.. important::
The database column of a rich text element should be a rich text field
in TCA (:php:`'enableRichtext' => true`), like `description`.
Otherwise, the backend shows the HTML source of the value. The column
`opening_times`, for example, is a plain text field and is **not** a
suitable target, unless you change its TCA.
The editor of an element is configured for the column
:yaml:`properties.dbMapping.column` of the table
:yaml:`properties.dbMapping.table`. The table is optional and defaults to
`tx_yellowpages2_domain_model_company`, the only table the
`SaveCompanyFinisher` stores values in.
.. _frontend-rich-text-editor-example-additional-element:
Example: Add a rich text editor to an additional form element
-------------------------------------------------------------
Add an own textarea to your copy of :file:`Company.form.yaml` and map it
to an own column of the company table, which you have configured with
:php:`'enableRichtext' => true` in TCA:
.. code-block:: yaml
:caption: EXT:my_sitepackage/Configuration/Form/Company.form.yaml (excerpt)
- label: 'Program'
type: Textarea
identifier: program
properties:
dbMapping:
column: tx_myext_program
# Optional: Instead of listing "program" in the site setting
dataType: richText
Map the element in the options of the `SaveCompanyFinisher`:
.. code-block:: yaml
:caption: EXT:my_sitepackage/Configuration/Form/Company.form.yaml (excerpt)
finishers:
1:
identifier: SaveCompanyFinisher
options:
table: tx_yellowpages2_domain_model_company
elements:
program:
mapOnDatabaseColumn: tx_myext_program
Then either keep :yaml:`dataType: richText` in the form definition or add
the identifier to the site setting:
.. code-block:: yaml
:caption: config/sites//settings.yaml
yellowpages2:
form:
richText:
enable: true
elements: 'description, program'
.. _frontend-rich-text-editor-assets:
Loaded files of the frontend rich text editor
=============================================
Rich text elements are rendered with the partial
:file:`EXT:yellowpages2/Resources/Private/FormFramework/Partials/RichTextEditor/Textarea.html`
(:yaml:`renderingOptions.templateName`). It is based on the partial
:file:`Textarea.html` of EXT:form and renders the partial
:file:`RichTextEditor/LoadAssets.html`, which loads the assets with the
ViewHelpers :html:`` and :html:``:
* The ES module `@jweiland/yellowpages2/rich-text-editor.js`
(:file:`EXT:yellowpages2/Resources/Public/JavaScript/rich-text-editor.js`)
creates an editor for each textarea with the attribute
:html:`data-yellowpages2-rich-text`. It loads the UI translation of the current
site language from
:confval:`yellowpages2.form.richText.translationsPath `.
* The style sheets :file:`EXT:rte_ckeditor/Resources/Public/Css/editor.css`
(identifier `yellowpages2-ckeditor`) and
:file:`EXT:yellowpages2/Resources/Public/Css/RichTextEditor.css` (identifier
`yellowpages2-rich-text-editor`).
The import map of the ES module and of the CKEditor modules is defined in
:file:`EXT:yellowpages2/Configuration/JavaScriptModules.php` and rendered by the
:php:`PageRenderer` of TYPO3 (:html:`