TYPO3 v15 dev-main snapshot ()
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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?
|
||||
@@ -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
|
||||
|
||||
@@ -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>`__
|
||||
@@ -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>`.
|
||||
@@ -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+|$))+' } }
|
||||
@@ -0,0 +1,11 @@
|
||||
# Minimal configuration for the editor
|
||||
editor:
|
||||
config:
|
||||
toolbar:
|
||||
items:
|
||||
- bold
|
||||
- italic
|
||||
- '|'
|
||||
- clipboard
|
||||
- undo
|
||||
- redo
|
||||
@@ -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' ] }
|
||||
@@ -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' ] }
|
||||
@@ -0,0 +1,8 @@
|
||||
# Minimal configuration for the editor
|
||||
editor:
|
||||
config:
|
||||
toolbar:
|
||||
items:
|
||||
- bold
|
||||
- italic
|
||||
- { label: 'Additional', icon: 'threeVerticalDots', items: [ 'specialCharacters', 'horizontalLine' ] }
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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',
|
||||
],
|
||||
];
|
||||
@@ -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
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 91 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Reference in New Issue
Block a user