first commit
This commit is contained in:
salam committed
commit
1218dd1517
12716 files changed
+989233
No files matched your search
@@ -0,0 +1,23 @@
|
||||
# EditorConfig is awesome: http://EditorConfig.org
|
||||
#
|
||||
# Use as master: https://github.com/TYPO3-Documentation/T3DocTeam/blob/master/.editorconfig
|
||||
|
||||
# top-most EditorConfig file
|
||||
root = false
|
||||
|
||||
[{*.rst,*.rst.txt}]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
indent_style = space
|
||||
indent_size = 3
|
||||
|
||||
# MD-Files
|
||||
[*.md]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
@@ -0,0 +1,57 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
.. _config-best-practices:
|
||||
|
||||
============================
|
||||
Configuration Best Practices
|
||||
============================
|
||||
|
||||
|
||||
.. _best-practice-sitepackage:
|
||||
|
||||
Use a Sitepackage Extension
|
||||
===========================
|
||||
|
||||
It is generally recommended to use a a sitepackage extension to
|
||||
customize a TYPO3 website. This will contain configuration files
|
||||
for the site.
|
||||
|
||||
For more information about sitepackages in TYPO3 see:
|
||||
|
||||
* Benjamin Kott: `"The Anatomy of Sitepackages"
|
||||
<https://www.slideshare.net/benjaminkott/typo3-the-anatomy-of-sitepackages>`__ (Slideshare)
|
||||
* :ref:`t3sitepackage:start`
|
||||
|
||||
.. TODO Explain Create an extension, add ext_localconf.php, start over and copy over the Default.yml file
|
||||
|
||||
Use TYPO3’s Core Default.yaml as boilerplate
|
||||
============================================
|
||||
|
||||
Instead of starting from scratch when writing custom configurations, it is
|
||||
recommended to copy TYPO3’s configuration file
|
||||
:file:`typo3/sysext/rte_ckeditor/Configuration/RTE/Default.yml`
|
||||
into your extension folder :file:`<extkey>/Configuration/RTE/`.
|
||||
|
||||
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.yml`
|
||||
|
||||
|
||||
Use Core Includes
|
||||
=================
|
||||
|
||||
.. todo: clarification needed: add examples, explanation
|
||||
|
||||
The base processing configuration for “transformations” (key “processing”)
|
||||
is written in a way that is restrictive on the one hand, but also allows
|
||||
to be extended.
|
||||
|
||||
The include files are already split up so transformations can just be included
|
||||
or even completely disabled (by removing the line for importing) to have CKEditor
|
||||
take care of all security measures.
|
||||
|
||||
@@ -0,0 +1,343 @@
|
||||
.. include:: ../Includes.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
|
||||
----
|
||||
|
||||
For TYPO3 v8 the ability to configure editor-related configuration and transformations
|
||||
via Yaml (Yet-Another-Markup-Language) was made available and is usable for both CKEditor
|
||||
and HtmlArea, although for the latter it is recommended to use the existing configuration
|
||||
when having special setups.
|
||||
|
||||
.. todo: add link to general information about configuration with Yaml, once available
|
||||
|
||||
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:`LocalConfiguration.php`,
|
||||
:file:`AdditionalConfiguration.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:lang/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:columns-text-properties-enableRichtext`,
|
||||
and a specific configuration
|
||||
can be set via :ref:`t3tca:columns-text-properties-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:: typoscript
|
||||
|
||||
# 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:
|
||||
|
||||
.. code-block:: typoscript
|
||||
|
||||
# Allow iframe tag with all attributes and all styles in bodytext field of content elements (Requires additional processing configuration)
|
||||
RTE.config.tt_content.bodytext.editor.config.extraAllowedContent = iframe[*]{*}
|
||||
# Restrict format_tags to h2 in bodytext field of content elements
|
||||
RTE.config.tt_content.bodytext.editor.config.format_tags = h2
|
||||
|
||||
For more examples, see :ref:`t3tsconfig: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.
|
||||
|
||||
.. todo: diagram rte -> DB -> RTE
|
||||
todo: add examples for transformations
|
||||
todo: possibly move most of this part to TYPO3 explained:
|
||||
https://docs.typo3.org/typo3cms/CoreApiReference/latest/ApiOverview/Rte/Transformations/Index.html
|
||||
|
||||
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 template.
|
||||
|
||||
Fluid
|
||||
-----
|
||||
|
||||
Outputting the contents of a RTE-enabled database field within Fluid can
|
||||
be achieved by adding :html:`<f:format.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:`Web > Template` and use the TypoScript Object Browser (Setup)
|
||||
to see if :typoscript:`lib.parseFunc_RTE` is filled.
|
||||
|
||||
.. todo: [SCREENSHOT of TSOB having lib.parseFunc_RTE open]
|
||||
|
||||
.. important::
|
||||
If you add your opening and closing tags on an own line, the rendered output
|
||||
includes empty paragraphs at beginning and end.
|
||||
|
||||
.. tip::
|
||||
In some cases it is an advantage to use the fluid inline notation to output the contents
|
||||
of a RTE-enabled database field: :html:`{record.myfield -> f:format.html()}`. This makes
|
||||
it easier to process the output further (e.g. by chaining Fluid ViewHelpers).
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,189 @@
|
||||
.. include:: ../Includes.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. In case you are , 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
|
||||
=============
|
||||
|
||||
Relevant Settings for `rte_ckeditor`
|
||||
------------------------------------
|
||||
|
||||
Page TSconfig can be used to change:
|
||||
|
||||
#. Default preset::
|
||||
|
||||
RTE.default.preset = full
|
||||
|
||||
#. Override for one field (:ts:`RTE.config.[tableName].[fieldName].preset`)::
|
||||
|
||||
RTE.config.tt_content.bodytext.preset = myCustomPreset
|
||||
RTE.config.tx_news_domain_model_news.bodytext.preset = minimal
|
||||
|
||||
#. Override for one field defined in flexform (:ts:`RTE.config.[tableName].[flexForm\.field\.name].preset`)::
|
||||
|
||||
RTE.config.tt_content.settings\.notifications\.emailText.preset = myCustomPreset
|
||||
|
||||
#. Override for one field, if type matches (:ts:`RTE.config.[tableName].[fieldName].types.[type].preset`)::
|
||||
|
||||
RTE.config.tt_content.bodytext.types.textmedia.preset = minimal
|
||||
|
||||
For more examples, see :ref:`t3tsconfig:pageTsRte` in "TSconfig Reference".
|
||||
|
||||
How to change values
|
||||
--------------------
|
||||
|
||||
As Page TSconfig always applies to a page and its subpages, you can modify it by
|
||||
editing a page.
|
||||
|
||||
#. Go to the :guilabel:`"WEB" > "Page"` module.
|
||||
#. Select a page in the page tree (usually
|
||||
your root page).
|
||||
#. Click on the button to :guilabel:`Edit page properties`
|
||||
|
||||
.. figure:: images/edit_page_properties.png
|
||||
:class: with-shadow
|
||||
|
||||
#. Select the :guilabel:`"Resources"` tab
|
||||
#. Enter the Page TSconfig in the field :guilabel:`"Page TSconfig"`
|
||||
|
||||
|
||||
Additionally, you can add Page TSconfig in an extension: :file:`Configuration/TSconfig/Page`, see
|
||||
:ref:`best-practice-sitepackage`.
|
||||
|
||||
How to view settings
|
||||
--------------------
|
||||
|
||||
Go to the module :guilabel:`"WEB" > "Info"` and select :guilabel:`"Page TSconfig"`.
|
||||
|
||||
|
||||
|
||||
|
||||
.. _config-typo3-global-configuration:
|
||||
|
||||
Global Configuration
|
||||
====================
|
||||
|
||||
Global Configuration is 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:`"ADMIN TOOLS" > "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:`typo3conf/AdditionalConfiguration.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:
|
||||
|
||||
TCA
|
||||
===
|
||||
|
||||
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:columns-text-properties-enableRichtext`
|
||||
* :ref:`t3tca:columns-text-properties-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 > columnOverrides`.
|
||||
|
||||
.. figure:: images/column_overrides.png
|
||||
:class: with-shadow
|
||||
|
||||
TCA: tt_content > types > text > columnsOverride > bodytext
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,197 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
.. _config-examples:
|
||||
|
||||
======================
|
||||
Configuration Examples
|
||||
======================
|
||||
|
||||
.. tip::
|
||||
|
||||
Use the CKEditor `Toolbar Configurator
|
||||
<https://ckeditor.com/latest/samples/toolbarconfigurator/index.html#basic>`__
|
||||
to assist you in creating your custom configuration.
|
||||
|
||||
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:: typoscript
|
||||
|
||||
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:: typoscript
|
||||
|
||||
RTE.config.tt_content.bodytext.preset = full
|
||||
|
||||
To use preset "minimal" for the field "bodytext" of only content elements
|
||||
with ctype="text":
|
||||
|
||||
.. code-block:: typoscript
|
||||
|
||||
RTE.config.tt_content.bodytext.types.text.preset = minimal
|
||||
|
||||
For more examples, see :ref:`t3tsconfig: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
|
||||
|
||||
$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:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# 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"
|
||||
|
||||
How Do I Customize the Toolbar?
|
||||
===============================
|
||||
|
||||
Since CKEditor 4, there are 2 ways to customize the toolbar buttons:
|
||||
|
||||
#. Using `editor.config.toolbar
|
||||
<https://ckeditor.com/docs/ckeditor4/latest/guide/dev_toolbarconcepts.html#item-by-item-configuration>`_
|
||||
: This has the advantage, that each button is configured individually and it gives
|
||||
you more control over what is displayed in the toolbar.
|
||||
#. Using `editor.config.toolbarGroups
|
||||
<https://ckeditor.com/docs/ckeditor4/latest/guide/dev_toolbarconcepts.html#toolbar-groups-configuration>`__
|
||||
: This has the advantage, that new buttons
|
||||
that have been added by plugins will automatically appear.
|
||||
|
||||
This is explained in the
|
||||
`Toolbar documentation <https://ckeditor.com/latest/samples/old/toolbar/toolbar.html>`__
|
||||
|
||||
.. _config-example-toolbargroup:
|
||||
|
||||
Configuration Using the toolbarGroups Method
|
||||
--------------------------------------------
|
||||
|
||||
Each button is in a specific toolbarGroup. You can configure various toolbars, containing
|
||||
one or more toolbarGroups.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
toolbarGroups:
|
||||
- { name: clipboard, groups: [ clipboard, cleanup, undo ] }
|
||||
|
||||
In the example, the toolbar "clipboard" will contain the toolbarGroups "clipboard", "cleanup" and
|
||||
"undo" and all buttons which are assigned to these groups will be displayed in the toolbar
|
||||
in the defined order.
|
||||
|
||||
To find out which buttons exist and which are in which toolbar group, you can
|
||||
go to the `toolbar configurator <https://ckeditor.com/latest/samples/toolbarconfigurator/index.html#basic>`__.
|
||||
|
||||
While you hover over the various toolbars, a selection box corresponding to the toolbar
|
||||
will be displayed in the sample toolbar at the top.
|
||||
|
||||
.. image:: images/toolbargroups.png
|
||||
:class: with-shadow
|
||||
|
||||
When you are ready, click :guilabel:`"Get toolbar config"` to see the configuration.
|
||||
|
||||
How do I add Custom Plugins?
|
||||
============================
|
||||
|
||||
See `EXT:rte_ckeditor/Configuration/RTE/Editor/Plugins.yml
|
||||
<https://github.com/TYPO3/TYPO3.CMS/blob/9.5/typo3/sysext/rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml>`__
|
||||
for a list of plugins, that are already integrated in `rte_ckeditor`. Besides this, the wordcount plugin was added as
|
||||
npm package. You can find it within :file:`typo3/sysext/rte_ckeditor/Resources/Public/JavaScript/Contrib/plugins/wordcount/`.
|
||||
|
||||
Additionally, a large number of `plugins <https://ckeditor.com/cke4/addons/plugins/all>`__
|
||||
are available and can be freely used.
|
||||
|
||||
|
||||
In this example, we integrate the plugin `codesnippet <https://ckeditor.com/cke4/addon/codesnippet>`__.
|
||||
|
||||
.. rst-class:: bignums
|
||||
|
||||
1. Go to the start page of the plugin
|
||||
|
||||
For example: `codesnippet <https://ckeditor.com/cke4/addon/codesnippet>`__.
|
||||
|
||||
2. Click :guilabel:`Download`
|
||||
|
||||
3. Unzip the plugin zip archive,
|
||||
|
||||
For example extract the files to the directory
|
||||
:file:`my_extension/Resources/Public/CKeditor/Plugins/codesnippet/`
|
||||
|
||||
4. Include the path to the plugin in your Yaml configuration, for example:
|
||||
|
||||
:file:`EXT:my_extension/Configuration/RTE/MyPreset.yaml`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
editor:
|
||||
externalPlugins:
|
||||
codesnippet:
|
||||
resource: "EXT:my_extension/Resources/Public/CKeditor/Plugins/codesnippet/"
|
||||
|
||||
.. tip::
|
||||
Each CKEditor plugin must have a javascript file called :file:`plugin.js` per convention.
|
||||
If this is not the case, you must reference the whole path including the javascript file.
|
||||
|
||||
5. Configure
|
||||
|
||||
Check if further configuration is necessary, by looking in the plugin documentation
|
||||
|
||||
.. todo: link to an example configuration of a CKEditor plugin (example config e.g. of "wordcount" plugin)
|
||||
|
||||
6. Make sure the new button is visible in the toolbar
|
||||
|
||||
Now, remove cache and reopen a text element, look for the new button
|
||||
"Insert Code Snippet".
|
||||
|
||||
If the button is not displayed, it is possible, that the toolbarGroup has not
|
||||
been activated. Search for "toolbar" in the plugin to find out which toolbarGroup
|
||||
is being used, in the case of the plugin "codesnippet", it is the toolbarGroup
|
||||
"insert". This should be activated by default.
|
||||
|
||||
7. Use the plugin
|
||||
|
||||
.. image:: images/codesnippet.png
|
||||
:class: with-shadow
|
||||
|
||||
|
||||
.. -------------------------------------
|
||||
.. 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.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,81 @@
|
||||
.. include:: ../Includes.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 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
|
||||
:file:`EXT:rte_ckeditor/Configuration/RTE/Full.yaml` as example (see latest 9.5
|
||||
`Full.yaml <https://github.com/TYPO3/TYPO3.CMS/blob/9.5/typo3/sysext/rte_ckeditor/Configuration/RTE/Full.yaml>`__)
|
||||
|
||||
We explain the example 'Minimal.yaml' from the core:
|
||||
|
||||
.. code-block:: yaml
|
||||
:linenos:
|
||||
|
||||
# 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:
|
||||
toolbarGroups:
|
||||
- { name: basicstyles, groups: [ basicstyles] }
|
||||
- { name: clipboard, groups: [clipboard, undo] }
|
||||
removeButtons:
|
||||
- Anchor
|
||||
- Superscript
|
||||
- Subscript
|
||||
- Underline
|
||||
- Strike
|
||||
|
||||
* line #2: imports existing files to make basic parts reusable and improve structure
|
||||
of configuration
|
||||
* line #9: toolbarGroups, see `toolbarGroups
|
||||
<https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html#cfg-toolbarGroups>`__
|
||||
and `Understanding CKEditor Toolbar Concepts
|
||||
<https://ckeditor.com/docs/ckeditor4/latest/guide/dev_toolbarconcepts.html>`__
|
||||
* line #12: removeButtons: this deactivates default buttons rendered in the toolbar, see `removeButtons
|
||||
<https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html#cfg-removeButtons>`__
|
||||
@@ -0,0 +1,121 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
.. _config-ref:
|
||||
|
||||
=======================
|
||||
Configuration Reference
|
||||
=======================
|
||||
|
||||
.. _config-ref-yaml:
|
||||
|
||||
Yaml Configuration Reference
|
||||
============================
|
||||
|
||||
When configurating the CKEditor using Yaml, these are the property
|
||||
names that are currently used:
|
||||
|
||||
* processing
|
||||
* editor
|
||||
|
||||
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 subproperties 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 Typolink.js plugin, or adding third-party plugins
|
||||
like handling images.
|
||||
|
||||
editor.config
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. todo: rewrite this section to optimize the UX and look and feel
|
||||
|
||||
editor.config:
|
||||
Configuration options For a list of all options see
|
||||
https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html
|
||||
|
||||
editor.config.language
|
||||
defines the editor’s UI language, and is dynamically calculated (if not set otherwise) by
|
||||
the backend users’ preference.
|
||||
|
||||
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.
|
||||
|
||||
editor.config.contentsCss
|
||||
defines the CSS file of the editor and the styles that can be applied.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
editor.config.contentCss: "EXT:rte_ckeditor/Resources/Public/Css/contents.css"
|
||||
|
||||
This is the default, as defined in `EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yml
|
||||
<https://github.com/TYPO3/TYPO3.CMS/blob/9.5/typo3/sysext/rte_ckeditor/Configuration/RTE/Editor/Base.yaml>`__.
|
||||
|
||||
editor.config.style
|
||||
Sets the style
|
||||
|
||||
editor.config.toolbarGroup
|
||||
This defines, which toolbarGroups (and corresponding buttons) will be
|
||||
visible in the toolbar.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
toolbarGroups:
|
||||
- { name: clipboard, groups: [ clipboard, cleanup, undo ] }
|
||||
|
||||
See :ref:`config-example-toolbargroup` for
|
||||
more information.
|
||||
|
||||
editor.config.removeButtons
|
||||
deactivates default buttons rendered in the toolbar.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
removeButtons:
|
||||
- Anchor
|
||||
- Superscript
|
||||
- Subscript
|
||||
- Underline
|
||||
- Strike
|
||||
|
||||
|
||||
See `removeButtons
|
||||
<https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html#cfg-removeButtons>`__
|
||||
for more information.
|
||||
|
||||
editor.*
|
||||
~~~~~~~~
|
||||
|
||||
editor.externalPlugins
|
||||
is a list of plugins with their routes and additional configuration options,
|
||||
the main “resource” subproperty needs to be set which is a JavaScript file
|
||||
using CKEditor’s plugin API, see `rte_ckeditor/Configuration/RTE/Editor/Plugins.yml
|
||||
<https://github.com/TYPO3/TYPO3.CMS/blob/9.5/typo3/sysext/rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml>`__.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 91 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
@@ -0,0 +1,30 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
.. _general-concepts:
|
||||
|
||||
================
|
||||
General Concepts
|
||||
================
|
||||
|
||||
Editing Modes
|
||||
=============
|
||||
|
||||
CKEditor has three editing modes:
|
||||
|
||||
* **“Article Editor”** mode (classic RTE): Editing is done within a fixed container.
|
||||
It is possible to customize how the editor behaves and how the content is styled.
|
||||
* **“Document Editor”** mode: Editing is done as in Microsoft Word or Google Docs,
|
||||
where the document itself mimics a sheet of paper. The focus is on structuring
|
||||
content and not mainly on the layout itself.
|
||||
* **“Inline Editor”** mode: All formatting styles are reused from the surrounding
|
||||
HTML and CSS styles, allowing for a seamless frontend editing.
|
||||
|
||||
“Article Editor” mode is used in the TYPO3 Backend.
|
||||
|
||||
“Inline Editor mode” is used by TYPO3’s “frontend_editing” which can be found on GitHub
|
||||
(`frontend_editing <https://github.com/FriendsOfTYPO3/frontend_editing>`__.
|
||||
Frontend_editing is not covered in this document.
|
||||
|
||||
For a demonstration of all three modes, see the
|
||||
`CKEditor demo <https://ckeditor.com/ckeditor-4/demo/#article>`__.
|
||||
@@ -0,0 +1,23 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. This is 'Includes.txt'. It is included at the very top of each and
|
||||
every ReST source file in this documentation project (= manual).
|
||||
|
||||
|
||||
.. ==================================================
|
||||
.. DEFINE SOME TEXT ROLES
|
||||
.. --------------------------------------------------
|
||||
|
||||
.. role:: html(code)
|
||||
|
||||
.. role:: typoscript(code)
|
||||
|
||||
.. role:: ts(typoscript)
|
||||
:class: typoscript
|
||||
|
||||
.. role:: php(code)
|
||||
|
||||
.. highlight:: php
|
||||
@@ -0,0 +1,48 @@
|
||||
.. include:: Includes.txt
|
||||
|
||||
.. _rte_ckeditor:
|
||||
.. _start:
|
||||
|
||||
============
|
||||
rte_ckeditor
|
||||
============
|
||||
|
||||
.. only:: html
|
||||
|
||||
:Extension key:
|
||||
rte_ckeditor
|
||||
|
||||
:Version:
|
||||
|release|
|
||||
|
||||
:Language:
|
||||
en
|
||||
|
||||
:Description:
|
||||
Integration of CKEditor 4 into TYPO3 for RTE editing
|
||||
|
||||
:Keywords:
|
||||
sysext, rte, ckeditor, cke4
|
||||
|
||||
:Copyright:
|
||||
2019-2021
|
||||
|
||||
:Author:
|
||||
Initial version by Benni Mack, updated and maintained by the TYPO3 community
|
||||
|
||||
:License:
|
||||
This document is published under the Open Publication License
|
||||
available from http://www.opencontent.org/openpub/
|
||||
|
||||
The content of this document is related to TYPO3,
|
||||
a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Introduction/Index
|
||||
GeneralConcepts/Index
|
||||
Installation/Index
|
||||
Configuration/Index
|
||||
Usage/Index
|
||||
Sitemap
|
||||
@@ -0,0 +1,26 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
.. _installation:
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
TYPO3 v9 and higher
|
||||
===================
|
||||
|
||||
For installations since TYPO3 version 9, `rte_ckeditor` is activated by
|
||||
default and ships with a default configuration for editors.
|
||||
|
||||
If you installed TYPO3 via composer with "subtree split", you must install
|
||||
the extension, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
composer require typo3/cms-rte-ckeditor:~9.5
|
||||
|
||||
See :ref:`t3coreapi:extension-install` in TYPO3 Explained for more information
|
||||
about installing extensions.
|
||||
|
||||
.. todo: screenshot of extension manager?
|
||||
@@ -0,0 +1,69 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
.. _introduction:
|
||||
|
||||
============
|
||||
Introduction
|
||||
============
|
||||
|
||||
|
||||
.. _what-it-does:
|
||||
|
||||
What does it do?
|
||||
================
|
||||
|
||||
The extension `rte_ckeditor` provides a rich text editor (RTE) by integrating
|
||||
`CKEditor 4 <https://ckeditor.com/ckeditor-4/>`__ into TYPO3.
|
||||
|
||||
This makes it possible to
|
||||
use the features of CKEditor when editing rich text fields in the TYPO3
|
||||
backend or frontend (if frontend editing is used). Rich text fields are
|
||||
fields which may contain text with markup, for example for adding a style
|
||||
such as bold, using lists or enumerations, headlines or adding links.
|
||||
|
||||
.. figure:: images/example_textfield.png
|
||||
:class: with-shadow
|
||||
|
||||
Editing a textfield in the backend with rte_ckeditor.
|
||||
|
||||
CKEditor is a :abbr:`WYSIWYG (what you see is what you get)` editor mostly written
|
||||
in JavaScript, and is used in many systems due to its flexibility. There are hundreds
|
||||
of free open-source plugins for CKEditor to enhance the editing experience.
|
||||
|
||||
History
|
||||
=======
|
||||
|
||||
CKEditor was officially integrated as the default rich text editor in TYPO3 v8 LTS,
|
||||
within an extension called `rte_ckeditor`.
|
||||
|
||||
Before TYPO3 v8, a custom fork of “HtmlArea”, another open-source WYSIWYG editor
|
||||
was shipped with TYPO3 Core in a separate extension `rtehtmlarea`. "HtmlArea"
|
||||
isn't supported anymore since TYPO3 v9 LTS. You have to migrate to `rte_ckeditor`
|
||||
when upgrading from previous TYPO3 versions (=< v8).
|
||||
|
||||
It's highly recommended to use CKEditor as the editor in TYPO3 v8 LTS instances.
|
||||
|
||||
.. _features:
|
||||
|
||||
Features
|
||||
========
|
||||
|
||||
|
||||
The extension `rte_ckeditor` incorporates the features of CKEditor and adds
|
||||
additional functionality, configuration presets and plugins.
|
||||
|
||||
There are numerous `plugins <https://ckeditor.com/cke4/addons/plugins/all>`__
|
||||
available for CKeditor. Some plugins have already been
|
||||
integrated into `rte_ckeditor` and new plugins have been written for TYPO3.
|
||||
|
||||
Some examples of features:
|
||||
|
||||
* Configurable via Yaml files
|
||||
* Configuration presets (minimal, default, full) for TYPO3
|
||||
* Toolbar customization
|
||||
* Link functionality: integration with TYPO3 link wizard
|
||||
* Softhypen: plugin for adding :kbd:`ctrl` + :kbd:`-` support to insert a conditional word break
|
||||
* Wordcount: plugin that counts and shows the chars/words/paragraphs in
|
||||
the footer of the editor. It also supports limiting the max. amount of chars/words.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
@@ -0,0 +1,61 @@
|
||||
# coding: utf-8
|
||||
|
||||
# #####
|
||||
#
|
||||
# Settings.cfg - A TYPO3 Documentation Project's Configuration File
|
||||
#
|
||||
# About Syntax:
|
||||
# See https://docs.python.org/2/library/configparser.html
|
||||
#
|
||||
# Attention:
|
||||
# Only " ;" can start an inline comment.
|
||||
# This is: blank PLUS semicolon!
|
||||
#
|
||||
# #####
|
||||
|
||||
[general]
|
||||
|
||||
project = Rich Text Editing in TYPO3 with CKEditor (rte_ckeditor)
|
||||
version = latest (10)
|
||||
release = latest (10)
|
||||
t3author = Initial version by Benni Mack, updated and maintained by the TYPO3 community
|
||||
copyright = 2019-2021
|
||||
|
||||
description = Integration of CKEditor into TYPO3 for rich text editing (RTE).
|
||||
|
||||
[html_theme_options]
|
||||
|
||||
# Add "Edit me on Github" button
|
||||
# core contribution is possible via Github PR
|
||||
github_branch = master
|
||||
github_repository = typo3/typo3
|
||||
path_to_documentation_dir = typo3/sysext/rte_ckeditor/Documentation
|
||||
|
||||
# Show as related links
|
||||
project_issues = https://forge.typo3.org/projects/typo3cms-core/issues
|
||||
project_repository = https://github.com/typo3/typo3
|
||||
|
||||
|
||||
|
||||
[intersphinx_mapping]
|
||||
|
||||
; Comment out what you don't use.
|
||||
; Uncomment only what you actually use in crossreferencing!
|
||||
|
||||
# t3api = https://typo3.org/api/typo3cms/
|
||||
# t3cgl = https://docs.typo3.org/typo3cms/CodingGuidelinesReference/
|
||||
t3coreapi = https://docs.typo3.org/typo3cms/CoreApiReference/
|
||||
t3editors = https://docs.typo3.org/typo3cms/EditorsTutorial/
|
||||
# t3extbasebook = https://docs.typo3.org/typo3cms/ExtbaseFluidBook/
|
||||
# t3install = https://docs.typo3.org/typo3cms/InstallationGuide/
|
||||
# t3l10n = https://docs.typo3.org/typo3cms/FrontendLocalizationGuide/
|
||||
# t3start = https://docs.typo3.org/typo3cms/GettingStartedTutorial/
|
||||
t3sitepackage = https://docs.typo3.org/typo3cms/SitePackageTutorial/
|
||||
t3tca = https://docs.typo3.org/typo3cms/TCAReference/
|
||||
# t3ts45 = https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/
|
||||
t3tsconfig = https://docs.typo3.org/typo3cms/TSconfigReference/
|
||||
t3tsref = https://docs.typo3.org/typo3cms/TyposcriptReference/
|
||||
|
||||
[extensions]
|
||||
any_name_youtube = sphinxcontrib.youtube
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
:template: sitemap.html
|
||||
|
||||
.. _sitemap:
|
||||
|
||||
=======
|
||||
Sitemap
|
||||
=======
|
||||
|
||||
.. template 'sitemap.html' will insert the toctree as a sitemap here below normal contents
|
||||
@@ -0,0 +1,38 @@
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
.. _usage:
|
||||
|
||||
===========
|
||||
Basic Usage
|
||||
===========
|
||||
|
||||
How the editor toolbar looks and what is available will depend on the
|
||||
currently used configuration.
|
||||
|
||||
The CKEditor will be active for RTE fields, for example the Text field
|
||||
of a content element.
|
||||
|
||||
For information about working with content elements, see the section
|
||||
:ref:`t3editors:content-editing` and :ref:`t3editors:rte` in the
|
||||
"Tutorial for Editors".
|
||||
|
||||
The following examples are done using the
|
||||
preset which is installed with the Introduction Package.
|
||||
|
||||
Example: Use bold
|
||||
=================
|
||||
|
||||
Select text and click on the **B** (for bold) button:
|
||||
|
||||
.. image:: images/rte_bold.png
|
||||
:class: with-shadow
|
||||
|
||||
|
||||
Example: Create a link
|
||||
======================
|
||||
|
||||
Select text and click on the Link button:
|
||||
|
||||
.. image:: images/rte_link.png
|
||||
:class: with-shadow
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Reference in new issue
Block a user