257 lines
8.7 KiB
ReStructuredText
257 lines
8.7 KiB
ReStructuredText
.. 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?
|