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