TYPO3 v15 dev-main snapshot ()
This commit is contained in:
@@ -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>`.
|
||||
Reference in New Issue
Block a user