TYPO3-translation/cms-rte-ckeditor
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TYPO3 v15 dev-main snapshot ()

Browse Source
This commit is contained in:
wappler
2026-08-10 22:31:36 +02:00
commit 1e393722e8
183 changed files with 7832 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/Configuration/BestPractices.rst
+83
View File
@@ -0,0 +1,83 @@
.. include:: /Includes.rst.txt
.. _config-best-practices:
============================
Configuration Best Practices
============================
.. _best-practice-sitepackage:
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 :doc:`TYPO3 Sitepackage Tutorial <t3sitepackage:Index>` 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
:file:`EXT:my_sitepackage/Configuration/RTE/`.
RTE configurations need to be registered in your sitepackages
:file:`ext_localconf.php`:
.. code-block:: php
:caption: EXT:my_sitepackage/ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['myconfig']
= 'EXT:my_sitepackage/Configuration/RTE/MyConfiguration.yaml';
.. note::
It is possible but not recommended to define this setting in the projects
:file:`system/settings.php` or :file:`system/additional.php`
.. _best-practice-boilerplate:
Use TYPO3’s Core Default.yaml as boilerplate
============================================
It is recommended to start by copying the file
:file:`typo3/sysext/rte_ckeditor/Configuration/RTE/Default.yaml` into your
sitepackage to the file
: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.
:file:`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:
.. code-block:: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyConfiguration.yaml
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
:ref:`Default.yaml as boilerplate <best-practice-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).
.. attention::
Please be aware that removing the :file:`Processing.yaml` removes
security measures. In that case you have to take care of keeping the ckeditor
safe yourself.
Documentation/Configuration/Concepts.rst
+350
View File
@@ -0,0 +1,350 @@
.. include:: /Includes.rst.txt
.. _config-concepts:
======================
Configuration Concepts
======================
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.
.. todo: diagram: overview with DB <-> RTE, DB -> FE etc.
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 :ref:`t3tsref:parsefunc`).
.. tip::
Before you start, have a look at the :ref:`config-best-practices`.
.. _config-editor:
Editor Configuration
====================
YAML
----
TYPO3 is using a custom :ref:`YAML API <t3coreapi:yaml-api>` for handling YAML
in TYPO3 based on the Symfony YAML package. Therefore environment variables
can be used.
YAML Basics
~~~~~~~~~~~
* YAML is case sensitive
* Indenting level reflects hierarchy level and indenting must be used consistently
(indent with 2 spaces in `rte_ckeditor` configuration).
* Comments begin with a `#`.
* White space is important, use a space after `:`.
This is a dictionary (associative array):
.. code-block:: yaml
key1: value
key2: value
A dictionary can be nested, for example:
.. code-block:: yaml
key1:
key1-2: value
This is a list:
.. code-block:: yaml
- list item 1
- list item 2
A dictionary can be combined with a list:
.. code-block:: yaml
key:
key2:
- item 1
- item 2
.. _configuration-presets:
Configuration Presets
---------------------
Presets are the heart of having custom configuration per record type, or
page area. A preset consists of a name and a reference to the location
of a YAML file.
TYPO3 ships with three RTE presets, “default”, “minimal” and “full”. The
"default" configuration is active by default.
It is possible for extensions to ship their own preset like “news”, or “site_xyz”.
Registration of a preset happens within :file:`system/config.php`,
:file:`system/additional.php` or within
:file:`ext_localconf.php` of an extension:
.. code-block:: php
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default']
= 'EXT:rte_ckeditor/Configuration/RTE/Default.yaml';
This way, it is possible to override the default preset, for example by using
the configuration defined in a custom extension:
.. code-block:: php
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default']
= 'EXT:my_extension/Configuration/RTE/Default.yaml';
TYPO3 uses the “default” preset for all Rich-Text-Element fields. To use
a different preset throughout an installation or a branch of the website,
see :ref:`override-configuration-via-page-tsconfig`.
Selecting a specific preset for bullet lists can be done via TCA
configuration of a field. The following example shows the TCA configuration
for the sys_news database table, which can be found in
:file:`EXT:core/Configuration/TCA/sys_news.php`.
.. code-block:: php
'content' => [
'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.text',
'config' => [
'type' => 'text',
'cols' => 48,
'rows' => 5,
'enableRichtext' => true,
'richtextConfiguration' => 'default',
],
],
Enabling Rich Text Parsing itself is done via :ref:`t3tca:confval-text-enablerichtext`,
and a specific configuration
can be set via :ref:`t3tca:confval-text-richtextConfiguration`, setting it to for example
“news”.
.. _override-configuration-via-page-tsconfig:
Overriding Configuration via page TSconfig
------------------------------------------
Instead of overriding all TCA fields to use a custom preset, it is possible
to override this information via page TSconfig.
The option :typoscript:`RTE.default.preset = news` can also be set on a per-field
and per-type basis:
.. code-block:: tsconfig
:caption: EXT:my_sitepackage/Configuration/page.tsconfig
:linenos:
# per-field
RTE.config.tt_content.bodytext.preset = minimal
# per-type
RTE.config.tt_content.bodytext.types.bullets.preset = bullets
line #2
This sets the "minimal" preset for all bodytext fields of content elements.
line #4
This sets the "bullets" preset for all bodytext fields of content elements,
with Content Type “Bullet list” (CType=bullets).
Of course, any other specific option set via YAML can be overridden via Page TSconfig as well:
Specific options set via YAML can be overridden via page TSconfig as well - but
be aware that boolean values can not be set, and arrays are not merged but
overridden.
.. code-block:: tsconfig
:caption: EXT:my_sitepackage/Configuration/page.tsconfig
# Restrict format_tags to h2 in bodytext field of content elements
RTE.config.tt_content.bodytext.editor.config.format_tags = h2
The loading order for configuration is:
#. ``preset`` defined for a specific field via PageTS
#. ``richtextConfiguration`` defined for a specific field via TCA
#. general preset defined via page TSconfig
#. ``default``
For more examples, see :ref:`t3tsref:pageTsRte` in "TSconfig Reference".
.. _config-rte-transformations:
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
:ref:`RTE Transformations in TYPO3 Explained <t3coreapi:transformations-introduction>`.
.. todo: diagram rte -> DB -> RTE
A Brief Dive Into History
-------------------------
Back in the very old days of TYPO3, there was an RTE which only worked inside Microsoft
Internet Explorer 4 (within the system extension “`rte`”). All other editors of TYPO3 had
to write HTML by hand, which was very complicated with all the table-based layouts available.
Links were not set with a :html:`<a>` tag, but with a so-called :html:`<typolink 23,13 _blank>`
tag. Further tags were :html:`<typolist>` and :html:`<typohead>`, which were stored in the database
1:1. Since RTEs did not understand these special tags, they had to transform these special tags into
valid HTML tags. Additionally, TYPO3 did not store regular :html:`<p>` or :html:`<div>` tags but
treated every line without a surrounding HTML block element as :html:`<p>` tag. The frontend rendering
then added `<p>` tags for each line when parsing (see below).
Transformations were later used to allow :html:`<em>`/:html:`<strong>` tags instead of :html:`<b>`/:html:`<i>`
tags, while staying backwards-compatible.
A lot of transformation options have been dropped for TYPO3 v8, and the default configuration
for these transformations acts as a solid base. CKEditor itself includes features that work as
another security layer for disallowing injecting of certain HTML tags in the database.
For TYPO3 v8, the :html:`<typolink>` tag was migrated to proper :html:`<a>` tags with a special
:html:`<a href="t3://page?id=23">` syntax when linking to pages to ensure HTML valid output.
Additionally, all records that are edited and stored to the database now contain proper
<p> tags, and transformations for paragraph tags are only applied when not set yet.
Transformations for invalid links and images (still available in HtmlArea) are still in place.
Most logic related to transformations can be found within :php:`TYPO3\CMS\Core\Html\RteHtmlParser`.
.. _transformations-vs-acf:
Transformations vs. CKEditor’s Advanced Content Filter
------------------------------------------------------
TYPO3’s HtmlParser transformations were used to transform readable semi-HTML
code to a full-blown HTML rendering ready for the RTE and vice versa. Since
TYPO3 v8, magically adding :html:`<p>` tags or transforming :html:`<typolink>`
tags is not necessary anymore, which leaves transformations almost obsolete.
However, they can act as an extra fallback layer of security to filter out
disallowed tags when saving. TYPO3 v8 configuration ships with a generic
transformation configuration, which is mainly based on legacy functionality
shipped with TYPO3 nowadays.
However, CKEditor comes with a separate strategy of allowing which HTML tags
and attributes are allowed, and can be configured on an editor-level.
This configuration option is called “allowedContent”, the feature itself is
named `Advanced Content Filter <http://docs.ckeditor.com/#!/guide/dev_advanced_content_filter>`__
(ACF).
Activating CKEditor’s table plugin allows to add :html:`<table>`, :html:`<tr>`
tags etc. Enabling the link picker enables the usage of :html:`<a>` tags. CKEditor
cleans content right away which was e.g. copy-pasted from MS Word and does not
match the allowed tags.
.. _config-frontend:
Frontend Output Configuration
=============================
Mostly due to historical reasons, the frontend output added :html:`<p>` tags to each
line which is not wrapped in HTML. Additionally the :html:`<typolink>` tag was replaced
by :html:`<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 :html:`<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.
.. todo: [DIAGRAM DB => FE]
TypoScript
----------
As with every content that is rendered via TYPO3, this processing for the frontend
output of Rich-Text-Editing fields is done via TypoScript, more specifically within
the stdWrap property :ref:`t3tsref:parsefunc`. With Fluid Styled Content and CSS Styled
Content comes :typoscript:`lib.parseFunc` and :typoscript:`lib.parseFunc_RTE` which add
support for parsing :html:`<a>` and :html:`<link>` tags and dumping them into the typolink
functionality. The shipped TypoScript code looks like this:
.. code-block:: typoscript
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
}
}
}
If you already use Fluid Styled Content and CSS Styled Content and
you haven’t touched that area of TypoScript yet, you’re good to go
by including the TypoScript file.
Fluid
-----
Outputting the contents of a RTE-enabled database field within Fluid can
be achieved by adding :html:`{record.myfield -> f:format.html()}`
which in turn calls :typoscript:`stdWrap.parseFunc` with :typoscript:`lib.parseFunc_RTE`
thus applying the same logic. Just ensure that the :typoscript:`lib.parseFunc_RTE`
functionality is available.
You can check if this TypoScript snippet is loaded by using
:guilabel:`Sites > TypoScript` and use the TypoScript Tree (Setup)
to see if :typoscript:`lib.parseFunc_RTE` is filled.
.. todo: [SCREENSHOT of TSOB having lib.parseFunc_RTE open]
.. important::
Take care of where you add opening and closing tags, if you don't use the fluid inline notation.
If they are on an own line, the rendered output includes empty paragraphs at beginning and end.
Documentation/Configuration/ConfigureTypo3.rst
+178
View File
@@ -0,0 +1,178 @@
.. include:: /Includes.rst.txt
.. highlight:: typoscript
.. _config-typo3:
==========================
TYPO3 Configuration Basics
==========================
Just in case you are not familiar with how to configure TYPO3, we will
give you a very brief introduction. Otherwise, you can safely
skip this part and continue reading
:ref:`config-concepts`.
We only cover configuration methods that are used to configure `rte_ckeditor`.
.. _config-typo3-page-tsconfig:
Page TSconfig
=============
We recommend you to put all configurations for the preset in the
:ref:`YAML <config-typo3-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 :ref:`Page TSconfig
reference, chapter RTE <t3tsref:pageTsRte>`.
Relevant Settings for `rte_ckeditor`
------------------------------------
Page TSconfig can be used to change:
#. Default preset:
.. code-block:: tsconfig
RTE.default.preset = full
#. Override for one field (:typoscript:`RTE.config.[tableName].[fieldName].preset`):
.. code-block:: tsconfig
RTE.config.tt_content.bodytext.preset = myCustomPreset
RTE.config.tx_news_domain_model_news.bodytext.preset = minimal
#. Override for one field defined in flexform (:typoscript:`RTE.config.[tableName].[flexForm\.field\.name].preset`):
.. code-block:: tsconfig
RTE.config.tt_content.settings\.notifications\.emailText.preset = myCustomPreset
#. Override for one field, if type matches (:typoscript:`RTE.config.[tableName].[fieldName].types.[type].preset`):
.. code-block:: tsconfig
RTE.config.tt_content.bodytext.types.textmedia.preset = minimal
How to change values
--------------------
See the :ref:`Page TSconfig reference,
chapter Setting Page TSconfig <t3tsref:setting-page-tsconfig>`. This chapter
also explains how to verify the settings.
.. _config-typo3-global-configuration:
Global Configuration
====================
Global Configuration is a system-wide general configuration.
Relevant Settings for `rte_ckeditor`
------------------------------------
The setting :php:`$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']` is used to configure
the available presets for rich text editing.
By default, the presets "minimal", "default" and "full" are defined.
If you add a new preset, you must add it to this array.
How to change values
--------------------
Usually, Global Configuration can be configured in the backend in
:guilabel:`System > Settings > Configure Installation-Wide Options`.
However, the settings relevant for rich text editing, :php:`$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']`
cannot be configured in the backend.
You must either configure this in:
#. The file :file:`%config-dir%/system/additional.php`
#. Or in an extension in the file :file:`EXT:<extkey>/ext_localconf.php`
.. code-block:: php
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
:guilabel:`System > Configuration > $GLOBAL['TYPO3_CONF_VARS'] (Global Configuration) > RTE`.
.. figure:: images/global-configuration-rte.png
:class: with-shadow
Global Configuration: RTE > Presets
.. _config-typo3-yaml:
YAML
====
Most of the configuration of `rte_ckeditor` will be done in a YAML file.
Relevant Settings for `rte_ckeditor`
------------------------------------
See :ref:`config-ref`
How to change values
--------------------
This is done directly in the file. The YAML file should be included in a
sitepackage extension, see :ref:`best-practice-sitepackage`.
.. _config-typo3-tca:
CKEditor related TCA configuration
==================================
The :abbr:`table configuration array (TCA)` 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.
Relevant Settings for `rte_ckeditor`
------------------------------------
* :ref:`t3tca:confval-text-enablerichtext`
* :ref:`t3tca:confval-text-richtextConfiguration`
How to change values
--------------------
This must be done in an extension in :file:`Configuration/TCA`. Usually this is done within a custom sitepackage
extension, see :ref:`best-practice-sitepackage`.
How to view settings
--------------------
You can view TCA in the backend:
:guilabel:`System > Configuration > $GLOBAL['TCA'] (Table configuration array)`.
For example, look at :guilabel:`tt_content > columns > bodytext`.
However, you will
find that neither `enableRichtext`, nor `richtextConfiguration` is set here. They
are configured in :guilabel:`tt_content > types` for various content types, for example
look at :guilabel:`tt_content > types > text > columnsOverrides`.
.. figure:: images/column_overrides.png
:class: with-shadow
TCA: tt_content > types > text > columnsOverrides > bodytext
Documentation/Configuration/Examples.rst
+256
View File
@@ -0,0 +1,256 @@
.. include:: /Includes.rst.txt
.. _config-examples:
======================
Configuration Examples
======================
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**:
.. code-block:: tsconfig
:caption: EXT:my_sitepackage/Configuration/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:
.. code-block:: tsconfig
:caption: EXT:my_sitepackage/Configuration/page.tsconfig
RTE.config.tt_content.bodytext.preset = full
To use preset "minimal" for the field "bodytext" of only content elements
with ctype="text":
.. code-block:: tsconfig
:caption: EXT:my_sitepackage/Configuration/page.tsconfig
RTE.config.tt_content.bodytext.types.text.preset = minimal
For more examples, see :ref:`t3tsref:pageTsRte` in "TSconfig Reference".
How do I create my own preset?
==============================
In your sitepackage extension:
In :file:`ext_localconf.php`, replace `my_extension` with your extension key, replace `my_preset` and `MyPreset.yaml`
with the name of your preset.
.. code-block:: php
:caption: EXT:my_sitepackage/ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['my_preset']
= 'EXT:my_extension/Configuration/RTE/MyPreset.yaml';
In :file:`Configuration/RTE/MyPreset.yaml`, create your configuration, for example:
.. literalinclude:: _Examples/_MyPreset.yaml
:language: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
See also the note for :option:`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
:file:`EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml`:
.. literalinclude:: _Examples/_CustomizeToolbar.yaml
:language: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
The :yaml:`'|'` can be used as a separator between groups of toolbar items.
Additional configuration options are available in the official CKEditor 5
`Toolbar documentation <https://ckeditor.com/docs/ckeditor5/latest/features/toolbar/toolbar.html>`__
.. _config-example-toolbargrouping:
Grouping toolbar items in drop-downs
------------------------------------
To save space in the toolbar or to arrange the features thematically, it is
possible to group several items into a dropdown as shown in the following
example:
.. literalinclude:: _Examples/_GroupingToolbarItems.yaml
:language: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
How do I allow a specific tag?
==============================
Allowed content in CKEditor 5 is to be configured via the General HTML Support
plugin option :yaml:`config.htmlSupport`.
.. literalinclude:: _Examples/_AllowSpecificTag.yaml
:language: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
.. note::
:yaml:`config.htmlSupport` only applies to elements that are "known" to
CKEditor 5. Tags like :html:`<svg>` or custom elements like
:html:`<my-element>` are not configurable this way as
:yaml:`htmlSupport.allow` can only handle
elements that are defined in the `CKEditor 5 schema`_.
.. _CKEditor 5 schema: https://ckeditor.com/docs/ckeditor5/latest/features/html/general-html-support.html#enabling-custom-elements
.. _config-example-fontplugin:
How do I configure the font plugin?
===================================
.. versionadded:: 12.4.12
In order to use the font plugin, the RTE configuration needs to be adapted:
.. literalinclude:: _Examples/_FontPlugin.yaml
:language: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
More information can be found in the
`official documentation of CKEditor <https://ckeditor.com/docs/ckeditor5/latest/features/font.html>`__.
How do I enable the fullscreen plugin?
======================================
.. versionadded:: 13.4.16
In order to use the fullscreen plugin, the RTE configuration needs to be adapted:
.. literalinclude:: _Examples/_FullscreenPlugin.yaml
:language: yaml
:caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
More information can be found in the
`official documentation of CKEditor <https://ckeditor.com/docs/ckeditor5/latest/features/fullscreen.html>`__.
.. _config-example-customplugin:
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 :ref:`config-linkbrowser` for
the detailed reference, and :t3src:`rte_ckeditor/Configuration/RTE/Editor/LinkBrowser.yaml`
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 <https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/migration-from-ckeditor-4.html#plugins>`__
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 `CKEditor 5 plugin system <https://ckeditor.com/docs/ckeditor5/latest/installation/advanced/plugins.html>`__.
In this example, we integrate a simple timestamp plugin to CKEditor 5.
Make sure to replace `<my_extension>` with your extension key.
.. rst-class:: bignums
1. Create the plugin file
Add the following ES6 JavaScript code:
.. code-block:: javascript
:caption: 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;
});
}
}
2. Register the ES6 JavaScript
.. literalinclude:: _Examples/_timestamp-plugin_JavaScriptModules.php
:language: php
:caption: EXT:<my_extension>/Configuration/JavaScriptModules.php
3. Include the plugin in the CKEditor configuration
.. literalinclude:: _Examples/_timestamp-plugin.yaml
:language: yaml
:caption: EXT:<my_extension>/Configuration/RTE/MyPreset.yaml
:emphasize-lines: 4,14
:linenos:
The :yaml:`importModules` item in line 4 imports the previously registered ES6
module. The :yaml:`timestamp` item in line 14 adds the plugin to the toolbar.
4. Use the plugin
.. figure:: images/timestamp-plugin.png
:class: with-shadow
:alt: The custom timestamp plugin in the editor
The custom timestamp plugin in the editor
.. -------------------------------------
.. todo: additional questions
What are stylesets?
Some configuration can be done with Page TSconfig, some with TCA and some with YAML and some with either 2 or more of these. Why and what should be configured where?
How can I configure classes to anchor tags?
What is the contents.css?
How can I set specific classes for anchors?
How can I extend custom tags?
How can I add images?
How can I configure tables?
How can I add more attributes to anchor tags?
How can I allow / deny specific tags?
How to add custom styles for ul tags?
Documentation/Configuration/Index.rst
+22
View File
@@ -0,0 +1,22 @@
.. include:: /Includes.rst.txt
.. _configuration:
=============
Configuration
=============
You can use the shipped configuration and everything will work as preconfigured
(using the "default" preset).
.. toctree::
QuickStart
ConfigureTypo3
Concepts
BestPractices
Examples
Reference
Documentation/Configuration/QuickStart.rst
+62
View File
@@ -0,0 +1,62 @@
.. include:: /Includes.rst.txt
.. _config-quickstart:
========================
Configuration Quickstart
========================
Here we explain, how to modify the existing configuration in a few simple steps.
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
:guilabel:`System > Configuration` in the backend, choose
:guilabel:`$GLOBALS['TYPO3_CONF_VARS'] (Global Configuration)` and select
:guilabel:`RTE`:
.. figure:: images/global-configuration-rte.png
:class: with-shadow
Global Configuration: RTE > Presets
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
:ref:`best-practice-sitepackage`.
Override the configuration preset "default" by adding this in :file:`<my_extension>/ext_localconf.php`
(replace `my_extension` with your extension key):
.. code-block:: php
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:my_extension/Configuration/RTE/Default.yaml';
Add the file :file:`Configuration/RTE/Default.yaml` to your extension, use the file
:t3src:`rte_ckeditor/Configuration/RTE/Full.yaml` as example.
We explain the example :file:`Minimal.yaml` from the Core:
.. literalinclude:: _Quickstart/_Minimal.yaml
:language: yaml
:caption: EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml
:linenos:
line #2
Imports existing files to make basic parts reusable and improve structure of configuration
line #9 toolbar
See `toolbar <https://ckeditor.com/docs/ckeditor5/latest/features/toolbar/toolbar.html>`__
Documentation/Configuration/Reference.rst
+463
View File
@@ -0,0 +1,463 @@
.. include:: /Includes.rst.txt
.. _config-ref:
=======================
Configuration Reference
=======================
.. _config-ref-yaml:
YAML Configuration Reference
============================
When configuring the CKEditor using YAML, these are the property
names that are currently used:
.. contents::
:local:
:depth: 1
processing
----------
Configuring transformations kicks in the RteHtmlParser API of TYPO3, to
only allow certain HTML tags and attributes when saving the database or
leaving the database to the RTE. However, defining transformations towards
RTE is not really necessary anymore. Defining more strict processing options
when storing content in the database also needs to be ensured that CKEditor
allows this functionality too.
This configuration option was previously built within `RTE.proc` and can
still be overridden via Page TSconfig. Everything defined via “processing”
is available in RTE.proc and triggers RteHtmlParser options.
editor
------
Editor contains all RTE-specific options. All CKEditor-specific options, which one
could imagine are available under “config” property and handed over to CKEditor’s
instance-specific config array.
All other sub-properties are usually handled via TYPO3 and then injected in the
CKEditor instance at runtime. This is useful for registering extra plugins, like
the TYPO3 core does with a custom :file:`typo3-link.js` plugin, or adding
third-party plugins like handling images.
editor.config
~~~~~~~~~~~~~
.. option:: editor.config
Configuration options For a list of all options see
https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editorconfig-EditorConfig.html
.. note::
Some configuration options from the official CKEditor 5 documentation
do not apply to TYPO3, since they are related to specific plugins
(for example: CKBox, CloudServices) which are not bundled in TYPO3's
CKEditor build.
.. option:: editor.config.language
defines the editor’s UI language, and is dynamically calculated (if not set otherwise) by
the backend users’ preference.
.. option:: editor.config.contentsLanguage
defines the language of the data, which is fetched from the
sys_language information, but can be overridden by this option as well.
For referencing files, TYPO3's internal "EXT:" syntax can be used, for
using language labels, TYPO3's "LLL:" language functionality can be used.
.. option:: editor.config.contentsCss
defines the location of one or multiple CSS file(s) of the editor, containing the style
definitions that will be applied to the backend editor RTE element.
Example with single file:
.. code-block:: yaml
:caption: MyCKPreset.yaml
editor.config.contentsCss:
- "EXT:rte_ckeditor/Resources/Public/Css/contents.css"
This is the default, as defined in :t3src:`rte_ckeditor/Configuration/RTE/Editor/Base.yaml`.
Example with multiple files:
.. code-block:: yaml
:caption: MyCKPreset.yaml
editor.config.contentsCss:
- "EXT:rte_ckeditor/Resources/Public/Css/contents.css"
- "EXT:my_sitepackage/Resources/Public/Css/contents.css?v=2"
Since the CKEditor element is rendered within the page content of the TYPO3 backend
(and not in an iframe or web-component), all CSS declarations in that file
must refer to an actual element hierarchy ending like
:css:`#data_tt_content__2687__bodytext_ckeditor5 .ck-content`. To achieve this,
TYPO3 automatically parses the contents of the CSS file with a process called
"auto-prefixing" (via JavaScript, client-side) and converts all references to
that "virtual" root hierarchy.
A CSS declaration like :css:`:root { background-color: green }` gets turned into
:css:`#data_tt_content__2687__bodytext_ckeditor5 .ck-content { background-color: green; }`.
You can use a :css:`:root { ... }` declaration, for example to reset
relative/absolute sizes to ensure the CKEditor area being compatible to your
usual frontend CSS. Also using `body {...}` is viable.
.. note::
Referenced CSS stylesheets need to
be downloadable via :js:`fetch()` in order for the JavaScript-based
prefixing to work.
.. note::
Also note that the generated CSS file is cached by your browser. If you change
the contents of your CSS file, be sure to either reload the browser cache,
or use a directive like
:yaml:`editor.config.contentsCss: "EXT:my_sitepackage/Resources/Public/Css/contents.css?v=2"`
where you change the `?v=` URI string after any file modification to enforce
requesting an updated version of the file.
.. option:: editor.config.heading
Defines headings available in the heading dropdown.
Example:
.. code-block:: yaml
:caption: MyCKPreset.yaml
heading:
options:
- { model: 'heading2', view: 'h2', title: 'Heading 2' }
- { model: 'heading3', view: 'h3', title: 'Heading 3' }
- { model: 'heading4', view: 'h4', title: 'Heading 4' }
It is also possible to set a class for a heading by default
(for example, :html:`<h2 class="h2">`):
.. code-block:: yaml
:caption: MyCKPreset.yaml
heading:
options:
- { model: 'heading2', view: { name: 'h2', classes: 'h2' }, title: 'Heading 2' }
- { model: 'heading3', view: { name: 'h3', classes: 'h3' }, title: 'Heading 3' }
- { model: 'heading4', view: { name: 'h4', classes: 'h4' }, title: 'Heading 4' }
To be able to reset a heading to a paragraph, add also the :yaml:`paragraph`
option:
.. code-block:: yaml
:caption: MyCKPreset.yaml
:emphasize-lines: 3
heading:
options:
- { model: 'paragraph', title: 'Paragraph' }
- { model: 'heading2', view 'h2', title: 'Heading 2' }
# ...
A title can also be localized with `LLL:EXT:...`.
.. option:: editor.config.style
Defines styles available in the style dropdown.
Example:
.. code-block:: yaml
:caption: MyCKPreset.yaml
style:
definitions:
- { name: "Lead", element: "p", classes: ['lead'] }
- { name: "Multiple", element: "p", classes: ['first', 'second'] }
.. option:: editor.config.importModules
Imports custom CKEditor plugins. See :t3src:`rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml`
or :ref:`How do I create a custom plugin? <config-example-customplugin>`
for examples.
.. _config-linkbrowser:
Link Browser specific options
-----------------------------
There are more configuration options that can be defined in the YAML file of an RTE preset
related to the Link Browser, when managing hyperlinks inside the CKEditor.
Note that the Link Browser can also be displayed based on FormEngine TCA definitions. These
use similar configuration, but from their TCA PHP configuration, and unrelated to the YAML
definition.
The additional example file :t3src:`rte_ckeditor/Configuration/RTE/Editor/LinkBrowser.yaml`
lists all of the following options as an example.
These options are a bit fragmented, it is important to watch for the proper indentation as well
the proper option relation.
.. important::
Please note that these options are set at the topmost level, and **not** nested inside
the `editor` YAML structure.
A short overview:
* `allowedOptions` - allowed list of additional attribute boxes
* `allowedTypes` - list of allowed Link Types inside the RTE
* `classesAnchor` - list of default CSS and link target values per Link Type
* `buttons` - Additional sub-configuration array for specific dropdowns
* `buttons.link.options` - Global options for the Link Browser
* `buttons.link.relAttribute` - Configuration for the `rel` attribute block
* `buttons.link.queryParametersSelector` - Configuration for the `queryParameter` (URI arguments) attribute block
* `buttons.link.targetSelector` - Configuration for the `target` attribute block
* `buttons.link.properties.class.allowedClasses` - Allowed additional CSS classes in the `CSS` attribute block
* `buttons.link.[LinkType].properties.class.default` - Default CSS class per Link Type
* `classes` - Label definitions for CSS class names
allowedOptions
~~~~~~~~~~~~~~
This string contains a comma separated list of additional attributes used in the Link Browser.
Available field lists can be found in :t3src:`backend/Classes/Controller/AbstractLinkBrowserController.php`,
method :php:`getLinkAttributeFieldDefinitions()`.
Note that the attributes `target`, `class` and `rel` are displayed differently depending on
whether the Link Browser was opened for a TCA element, or a RTE element. See
:t3src:`rte_ckeditor/Classes/Controller/BrowseLinksController.php` in method
`getLinkAttributeFieldDefinitions()`.
Valid attributes keys are:
.. option:: target
If set, an input box for link target (for example "_blank") is available.
.. option:: title
If set, entering the link title is available.
.. option:: class
If set, allowing to enter a CSS class name for the link is available.
This needs to match the CSS classes made available to the CKEDitor instance.
.. option:: params
If set, additional parameters are allowed to be set for a link.
.. option:: rel
If set, relations (:html:`rel` attribute) for links can be set.
To set all of them, you can use:
.. code-block:: yaml
:caption: MyCKPreset.yaml
allowedOptions: 'target,title,class,params,rel'
To remove all options you can use an empty string:
.. code-block:: yaml
:caption: MyCKPreset.yaml
allowedOptions: ''
allowedTypes
~~~~~~~~~~~~
This string contains a comma-separated list of all allowed Link Types
for the Link Browser. These are currently:
* `page`
* `url`
* `file`
* `folder`
* `email`
* `...` any custom Link Type
.. code-block:: yaml
:caption: MyCKPreset.yaml
allowedTypes: 'page,url,file,folder,email,customType'
To remove all types you can use an empty string:
.. code-block:: yaml
:caption: MyCKPreset.yaml
allowedTypes: ''
classesAnchor
~~~~~~~~~~~~~
This is a sub-array of default CSS classes and target attributes, per Link Type:
.. code-block:: yaml
:caption: MyCKPreset.yaml
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" }
Note that the available CSS class here must also be part of the
`buttons.link.properties.class.allowedClasses` definition.
buttons.link
~~~~~~~~~~~~
This structure defines both global options as well as Link Type-specific
options:
buttons.link.options.removeItems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Can be set to exclude certain Link Types:
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
options:
removeItems: 'telephone'
buttons.link.relAttribute.enabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the `allowedOptions` string list contains `rel` for setting relation
attributes, this option must also be enabled:
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
relAttribute:
enabled: true
buttons.link.queryParametersSelector.enabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the `allowedOptions` string list contains `params` for setting URI argument
attributes, this option must also be enabled:
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
queryParametersSelector:
enabled: true
buttons.link.targetSelector.disabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the `allowedOptions` string list contains `target`, a dropdown is displayed by
default. If you want to hide it, you must set this option to `true`:
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
targetSelector:
disabled: true
buttons.link.properties.class.required
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A CSS class selection can be forced, so that it may not be empty:
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
properties:
class:
required: true
buttons.link.properties.class.allowedClasses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the most vital CSS class selection list, based on a comma-separated
string naming all CSS classes that are allowed. Default CSS classes per Link Type
can only be selected, if they are part of this list.
The names of the CSS classes can be adjusted via the `classes` top-level configuration
hierarchy (see below)
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
properties:
class:
allowedClasses: 'globalCss1,globalCss1,CustomPageCssClass'
buttons.link.[linkType].properties.class.default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For each Link Type, a default CSS class can be defined, using the name of the
Link Type as a key:
.. code-block:: yaml
:caption: MyCKPreset.yaml
buttons:
link:
telephone:
class:
default: "customTelephoneCssClass"
email:
class:
default: "customEmailCssClass"
Note that the CSS class listed here must also be contained in
`buttons.link.properties.class.allowedClasses`.
classes.[CssClassName]
~~~~~~~~~~~~~~~~~~~~~~
The list of CSS classes defined in `buttons.link.properties.class.allowedClasses`
can set a custom label as well as a styling the select option. Note that styling
select options does not work in every browser, and is not suggested to use.
The name of the structure key must match the CSS class name, with a sub-structure
defining `name` (the actual label) and `value` (the possible CSS styling of the option
inside the dropdown):
.. code-block:: yaml
:caption: MyCKPreset.yaml
classes:
globalCss1:
name: "A Label for globalCss1"
value: "color: red"
customEmailCssClass:
name: "An email-specific class for VIPs"
.. _config-ref-tsconfig:
Page TSconfig
=============
We recommend you to put all configurations for the preset in the
:ref:`YAML <config-typo3-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 :ref:`Page TSconfig
reference, chapter RTE <t3tsref:pageTsRte>`.
Documentation/Configuration/_Examples/_AllowSpecificTag.yaml
+14
View File
@@ -0,0 +1,14 @@
# 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:
# if you want to allow that an inline tag like `<i>` can also be empty
allowEmpty: ['i']
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+|$))+' } }
Documentation/Configuration/_Examples/_CustomizeToolbar.yaml
+11
View File
@@ -0,0 +1,11 @@
# Minimal configuration for the editor
editor:
config:
toolbar:
items:
- bold
- italic
- '|'
- clipboard
- undo
- redo
Documentation/Configuration/_Examples/_FontPlugin.yaml
+36
View File
@@ -0,0 +1,36 @@
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' ] }
Documentation/Configuration/_Examples/_FullscreenPlugin.yaml
+14
View File
@@ -0,0 +1,14 @@
editor:
config:
toolbar:
items:
# add button to enable fullscreen view
- fullscreen
fullscreen:
menuBar:
# Disable menu bar in fullscreen view
isVisible: false
importModules:
- { module: '@ckeditor/ckeditor5-fullscreen', exports: [ 'Fullscreen' ] }
Documentation/Configuration/_Examples/_GroupingToolbarItems.yaml
+8
View File
@@ -0,0 +1,8 @@
# Minimal configuration for the editor
editor:
config:
toolbar:
items:
- bold
- italic
- { label: 'Additional', icon: 'threeVerticalDots', items: [ 'specialCharacters', 'horizontalLine' ] }
Documentation/Configuration/_Examples/_MyPreset.yaml
+12
View File
@@ -0,0 +1,12 @@
# 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"
Documentation/Configuration/_Examples/_timestamp-plugin.yaml
+14
View File
@@ -0,0 +1,14 @@
editor:
config:
importModules:
- { module: '@my-vendor/my-package/timestamp-plugin.js', exports: [ 'Timestamp' ] }
toolbar:
items:
- bold
- italic
- '|'
- clipboard
- undo
- redo
- '|'
- timestamp
Documentation/Configuration/_Examples/_timestamp-plugin_JavaScriptModules.php
+8
View File
@@ -0,0 +1,8 @@
<?php
return [
'dependencies' => ['backend'],
'imports' => [
'@my-vendor/my-package/timestamp-plugin.js' => 'EXT:my_extension/Resources/Public/JavaScript/Ckeditor/timestamp-plugin.js',
],
];
Documentation/Configuration/_Quickstart/_Minimal.yaml
+16
View File
@@ -0,0 +1,16 @@
# 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
Documentation/Configuration/images/column_overrides.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

Documentation/Configuration/images/edit_page_properties.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

Documentation/Configuration/images/global-configuration-rte.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

Documentation/Configuration/images/timestamp-plugin.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

Documentation/GeneralConcepts/Index.rst
+30
View File
@@ -0,0 +1,30 @@
.. include:: /Includes.rst.txt
.. _general-concepts:
================
General Concepts
================
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 <https://github.com/FriendsOfTYPO3/frontend_editing>`__.
frontend_editing is not covered in this document.
For a demonstration of all user interfaces,
see the `CKEditor demo <https://ckeditor.com/ckeditor-5/demo/editor-types/>`__.
Documentation/Images/InstallActivate.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

Documentation/Includes.rst.txt
+1
View File
@@ -0,0 +1 @@
.. You can put central messages to display on all pages here
Documentation/Index.rst
+57
View File
@@ -0,0 +1,57 @@
.. include:: /Includes.rst.txt
.. _start:
=====================
TYPO3 RTE by CKEditor
=====================
:Extension key:
rte_ckeditor
:Package name:
typo3/cms-rte-ckeditor
:Version:
|release|
:Language:
en
:Author:
TYPO3 contributors
:License:
This document is published under the
`Open Content License <https://www.openhub.net/licenses/opl>`__.
:Rendered:
|today|
----
This extension integrates the `CKEditor`_ as a rich text editor into the TYPO3
backend.
.. _CKEditor: https://ckeditor.com/
----
**Table of Contents:**
.. toctree::
:maxdepth: 2
:titlesonly:
Introduction/Index
GeneralConcepts/Index
Installation/Index
Configuration/Index
Usage/Index
.. Meta Menu
.. toctree::
:hidden:
Sitemap
Documentation/Installation/Index.rst
+53
View File
@@ -0,0 +1,53 @@
.. include:: /Includes.rst.txt
.. _installation:
============
Installation
============
This extension is part of the TYPO3 Core.
.. contents:: Table of contents
:local:
Installation with Composer
==========================
Check whether you are already using the extension with:
.. code-block:: bash
composer show | grep rte
This should either give you no result or something similar to:
.. code-block:: none
typo3/cms-rte-ckeditor v12.4.11
If it is not installed yet, use the ``composer require`` command to install
the extension:
.. code-block:: bash
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:
#. In the backend, navigate to the :guilabel:`System > Extensions`
module.
#. Click the :guilabel:`Activate` icon for the RTE CKEditor extension.
.. figure:: /Images/InstallActivate.png
:class: with-border
:alt: Extension manager showing RTE CKEditor extension
Extension manager showing RTE CKEditor extension
Documentation/Introduction/Index.rst
+62
View File
@@ -0,0 +1,62 @@
.. include:: /Includes.rst.txt
.. _introduction:
============
Introduction
============
.. _what-it-does:
What does it do?
================
The extension `rte_ckeditor` provides a rich text editor (RTE) by integrating
`CKEditor 5 <https://ckeditor.com/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.
.. figure:: images/example_textfield.png
:class: with-shadow
Editing a textfield in the backend with rte_ckeditor.
CKEditor is a :abbr:`WYSIWYG (what you see is what you get)` 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:
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.
Documentation/Introduction/images/example_textfield.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 57 KiB

Documentation/Sitemap.rst
+9
View File
@@ -0,0 +1,9 @@
:template: sitemap.html
.. include:: /Includes.rst.txt
=======
Sitemap
=======
.. The sitemap.html template will insert here the page tree automatically.
Documentation/Usage/Index.rst
+38
View File
@@ -0,0 +1,38 @@
.. include:: /Includes.rst.txt
.. _usage:
===========
Basic Usage
===========
How the editor toolbar looks and what is available will depend on the
currently used configuration.
The CKEditor will be active for RTE fields, for example the Text field
of a content element.
For information about working with content elements, see the section
:ref:`t3editors:content-editing` and :ref:`t3editors:rte` in the
"Tutorial for Editors".
The following examples are done using the
preset which is installed with the Introduction Package.
Example: Use bold
=================
Select text and click on the **B** (for bold) button:
.. image:: images/rte_bold.png
:class: with-shadow
Example: Create a link
======================
Select text and click on the Link button:
.. image:: images/rte_link.png
:class: with-shadow
Documentation/Usage/images/rte_bold.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

Documentation/Usage/images/rte_link.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

Documentation/guides.xml
+21
View File
@@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
links-are-relative="true">
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://extensions.typo3.org/extension/rte_ckeditor/"
project-contact="https://typo3.slack.com/archives/C025BQLFA"
project-repository="https://github.com/typo3/typo3"
project-issues="https://forge.typo3.org/projects/typo3cms-core/issues"
edit-on-github-branch="main"
edit-on-github="typo3/typo3"
edit-on-github-directory="typo3/sysext/rte_ckeditor/Documentation/"
typo3-core-preferred="main"
interlink-shortcode="typo3/cms-rte-ckeditor"
/>
<project title="RTE by CKEditor"
release="main (development)"
version="main (development)"
copyright="since 2016 by the TYPO3 contributors"
/>
</guides>