[DOCS] Correct page TSconfig example when using types for presets
[Packages/TYPO3.CMS.git] / typo3 / sysext / rte_ckeditor / Documentation / Configuration / Concepts.rst
1 .. include:: ../Includes.txt
2
3
4 .. _config-concepts:
5
6 ======================
7 Configuration Concepts
8 ======================
9
10
11 Configuration Overview
12 ======================
13
14 The main principles of configuring a Rich Text Editor in TYPO3
15 apply to editing with any Rich Text Editor (`rte_ckeditor`, ...).
16
17 Some of the functionality (for example the RTE transformations) is
18 embedded in the TYPO3 core and not specific to `rte_ckeditor`.
19
20 There are three main parts relevant for rich text editing with TYPO3:
21
22 Editor configuration
23 This covers how the actual editor (in this case CKEditor) should behave,
24 what buttons should be shown, what options are available.
25
26 RTE transformations
27 This defines how the information is processed when saved from the Rich Text Editor to the database.
28 And when loaded from the database into the Rich Text Editor.
29
30 Frontend output configuration
31 The information fetched from the database may need to be processed for the frontend.
32 The configuration of the frontend output is configured via TypoScript.
33
34 .. todo: diagram: overview with DB <-> RTE, DB -> FE etc.
35
36 This section mainly covers editor configuration and RTE transformations, as for
37 TypoScript the TypoScript reference handles output of HTML content and
38 has everything preset (see :ref:`t3tsref:parsefunc`).
39
40
41 .. tip::
42
43 Before you start, have a look at the :ref:`config-best-practices`.
44
45
46 .. _config-editor:
47
48 Editor Configuration
49 ====================
50
51 YAML
52 ----
53
54 For TYPO3 v8 the ability to configure editor-related configuration and transformations
55 via YAML (Yet-Another-Markup-Language) was made available and is usable for both CKEditor
56 and HtmlArea, although for the latter it is recommended to use the existing configuration
57 when having special setups.
58
59 .. todo: add link to general information about configuration with YAML, once available
60
61 YAML Basics
62 ~~~~~~~~~~~
63
64 * YAML is case sensitive
65 * Indenting level reflects hierarchy level and indenting must be used consistently
66 (indent with 2 spaces in `rte_ckeditor` configuration).
67 * Comments begin with a `#`.
68 * White space is important, use a space after `:`.
69
70 This is a dictionary (associative array)::
71
72 key1: value
73 key2: value
74
75 A dictionary can be nested, for example::
76
77 key1:
78 key1-2: value
79
80 This is a list::
81
82 - list item 1
83 - list item 2
84
85 A dictionary can be combined with a list::
86
87 key:
88 key2:
89 - item 1
90 - item 2
91
92
93 .. configuration-presets:
94
95 Configuration Presets
96 ---------------------
97
98 Presets are the heart of having custom configuration per record type, or
99 page area. A preset consists of a name and a reference to the location
100 of a YAML file.
101
102 TYPO3 ships with three RTE presets, “default”, “minimal” and “full”. The
103 "default" configuration is active by default.
104
105 It is possible for extensions to ship their own preset like “news”, or “site_xyz”.
106
107 Registration of a preset happens within :file:`LocalConfiguration.php`,
108 :file:`AdditionalConfiguration.php` or within
109 :file:`ext_localconf.php` of an extension:
110
111 .. code-block:: php
112
113 $GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:rte_ckeditor/Configuration/RTE/Default.yaml';
114
115 This way, it is possible to override the default preset, for example by using
116 the configuration defined in a custom extension:
117
118 .. code-block:: php
119
120 $GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:my_extension/Configuration/RTE/Default.yaml';
121
122
123 TYPO3 uses the “default” preset for all Rich-Text-Element fields. To use
124 a different preset throughout an installation or a branch of the website,
125 see :ref:`override-configuration-via-page-tsconfig`.
126
127 Selecting a specific preset for bullet lists can be done via TCA
128 configuration of a field. The following example shows the TCA configuration
129 for the sys_news database table, which can be found in
130 :file:`EXT:core/Configuration/TCA/sys_news.php`.
131
132 .. code-block:: php
133
134 'content' => [
135 'label' => 'LLL:EXT:lang/Resources/Private/Language/locallang_general.xlf:LGL.text',
136 'config' => [
137 'type' => 'text',
138 'cols' => 48,
139 'rows' => 5,
140 'enableRichtext' => true,
141 'richtextConfiguration' => 'default',
142 ],
143
144 Enabling Rich Text Parsing itself is done via :ref:`t3tca:columns-text-properties-enableRichtext`,
145 and a specific configuration
146 can be set via :ref:`t3tca:columns-text-properties-richtextConfiguration`, setting it to for example
147 “news”.
148
149 .. _override-configuration-via-page-tsconfig:
150
151 Overriding Configuration via Page TSconfig
152 ------------------------------------------
153
154 Instead of overriding all TCA fields to use a custom preset, it is possible
155 to override this information via Page TSconfig.
156
157 The option :typoscript:`RTE.default.preset = news` can also be set on a per-field
158 and per-type basis:
159
160 .. code-block:: typoscript
161
162 # per-field
163 RTE.config.tt_content.bodytext.preset = minimal
164
165 # per-type
166 RTE.config.tt_content.bodytext.types.bullets.preset = bullets
167
168 line #2
169 This sets the "minimal" preset for all bodytext fields of content elements.
170
171 line #4
172 This sets the "bullets" preset for all bodytext fields of content elements,
173 with Content Type “Bullet list” (CType=bullets).
174
175 Of course, any other specific option set via YAML can be overridden via Page TSconfig as well:
176
177 .. code-block:: typoscript
178
179 # Allow iframe tag with all attributes and all styles in bodytext field of content elements (Requires additional processing configuration)
180 RTE.config.tt_content.bodytext.editor.config.extraAllowedContent = iframe[*]{*}
181 # Restrict format_tags to h2 in bodytext field of content elements
182 RTE.config.tt_content.bodytext.editor.config.format_tags = h2
183
184 The loading order for configuration is:
185
186 #. ``preset`` defined for a specific field via PageTS
187 #. ``richtextConfiguration`` defined for a specific field via TCA
188 #. general preset defined via PageTS
189 #. ``default``
190
191
192 For more examples, see :ref:`t3tsconfig:pageTsRte` in "TSconfig Reference".
193
194
195 .. _config-rte-transformations:
196
197 RTE Transformations
198 ===================
199
200 Transformations are directives for parsing HTML markup. They are executed by the
201 TYPO3 Core every time a RTE-based field is saved to the TYPO3 database or fetched
202 from the database for the Rich Text Editor to render. This way, there are always
203 two ways / two transformations applied.
204
205 There are several advantages for transformations, the most prominent reason is to
206 not inject bad HTML code into the database which in turn would be used for output.
207 Transformations from the RTE towards the database can filter out HTML tags or attributes.
208
209 .. todo: diagram rte -> DB -> RTE
210 todo: add examples for transformations
211 todo: possibly move most of this part to TYPO3 explained:
212 https://docs.typo3.org/typo3cms/CoreApiReference/latest/ApiOverview/Rte/Transformations/Index.html
213
214 A Brief Dive Into History
215 -------------------------
216
217 Back in the very old days of TYPO3, there was an RTE which only worked inside Microsoft
218 Internet Explorer 4 (within the system extension “`rte`”). All other editors of TYPO3 had
219 to write HTML by hand, which was very complicated with all the table-based layouts available.
220 Links were not set with a :html:`<a>` tag, but with a so-called :html:`<typolink 23,13 _blank>`
221 tag. Further tags were :html:`<typolist>` and :html:`<typohead>`, which were stored in the database
222 1:1. Since RTEs did not understand these special tags, they had to transform these special tags into
223 valid HTML tags. Additionally, TYPO3 did not store regular :html:`<p>` or :html:`<div>` tags but
224 treated every line without a surrounding HTML block element as :html:`<p>` tag. The frontend rendering
225 then added `<p>` tags for each line when parsing (see below).
226
227 Transformations were later used to allow :html:`<em>`/:html:`<strong>` tags instead of :html:`<b>`/:html:`<i>`
228 tags, while staying backwards-compatible.
229
230 A lot of transformation options have been dropped for TYPO3 v8, and the default configuration
231 for these transformations acts as a solid base. CKEditor itself includes features that work as
232 another security layer for disallowing injecting of certain HTML tags in the database.
233
234 For TYPO3 v8, the :html:`<typolink>` tag was migrated to proper :html:`<a>` tags with a special
235 :html:`<a href="t3://page?id=23">` syntax when linking to pages to ensure HTML valid output.
236 Additionally, all records that are edited and stored to the database now contain proper
237 <p> tags, and transformations for paragraph tags are only applied when not set yet.
238
239 Transformations for invalid links and images (still available in HtmlArea) are still in place.
240
241 Most logic related to transformations can be found within :php:`TYPO3\CMS\Core\Html\RteHtmlParser`.
242
243
244 .. _transformations-vs-acf:
245
246 Transformations vs. CKEditor’s Advanced Content Filter
247 ------------------------------------------------------
248
249 TYPO3’s HtmlParser transformations were used to transform readable semi-HTML
250 code to a full-blown HTML rendering ready for the RTE and vice versa. Since
251 TYPO3 v8, magically adding :html:`<p>` tags or transforming :html:`<typolink>`
252 tags is not necessary anymore, which leaves transformations almost obsolete.
253
254 However, they can act as an extra fallback layer of security to filter out
255 disallowed tags when saving. TYPO3 v8 configuration ships with a generic
256 transformation configuration, which is mainly based on legacy functionality
257 shipped with TYPO3 nowadays.
258
259 However, CKEditor comes with a separate strategy of allowing which HTML tags
260 and attributes are allowed, and can be configured on an editor-level.
261 This configuration option is called “allowedContent”, the feature itself is
262 named `Advanced Content Filter <http://docs.ckeditor.com/#!/guide/dev_advanced_content_filter>`__
263 (ACF).
264
265 Activating CKEditor’s table plugin allows to add :html:`<table>`, :html:`<tr>`
266 tags etc. Enabling the link picker enables the usage of :html:`<a>` tags. CKEditor
267 cleans content right away which was e.g. copy-pasted from MS Word and does not
268 match the allowed tags.
269
270
271 .. _config-frontend:
272
273 Frontend Output Configuration
274 =============================
275
276 Mostly due to historical reasons, the frontend output added :html:`<p>` tags to each
277 line which is not wrapped in HTML. Additionally the :html:`<typolink>` tag was replaced
278 by :html:`<a>` tags and checked if e.g. if a link was set to a specific page within
279 TYPO3 is actually accessible for this specific visitor.
280
281 The latter part is still necessary, so the :html:`<a href="t3://page?id23">` HTML snippet
282 is replaced by a speaking URL which the power of typolink will still take care of.
283 There are, of course, more options to it, like default “target” attributes for
284 external links or spam-protecting links to email addresses, which all happens within the
285 typolink logic, the master for generating a link in the TYPO3 Frontend rendering process.
286
287 .. todo: [DIAGRAM DB => FE]
288
289
290 TypoScript
291 ----------
292
293 As with every content that is rendered via TYPO3, this processing for the frontend
294 output of Rich-Text-Editing fields is done via TypoScript, more specifically within
295 the stdWrap property :ref:`t3tsref:parsefunc`. With Fluid Styled Content and CSS Styled
296 Content comes :typoscript:`lib.parseFunc` and :typoscript:`lib.parseFunc_RTE` which add
297 support for parsing :html:`<a>` and :html:`<link>` tags and dumping them into the typolink
298 functionality. The shipped TypoScript code looks like this:
299
300 .. code-block:: typoscript
301
302 lib.parseFunc.tags {
303 a = TEXT
304 a {
305 current = 1
306 typolink {
307 parameter.data = parameters:href
308 title.data = parameters:title
309 ATagParams.data = parameters:allParams
310 target.data = parameters:target
311 extTarget = {$styles.content.links.extTarget}
312 extTarget.override.data = parameters:target
313 }
314 }
315 }
316
317
318 If you already use Fluid Styled Content and CSS Styled Content and
319 you haven’t touched that area of TypoScript yet, you’re good to go
320 by including the TypoScript template.
321
322 Fluid
323 -----
324
325 Outputting the contents of a RTE-enabled database field within Fluid can
326 be achieved by adding :html:`{record.myfield -> f:format.html()}`
327 which in turn calls :typoscript:`stdWrap.parseFunc` with :typoscript:`lib.parseFunc_RTE`
328 thus applying the same logic. Just ensure that the :typoscript:`lib.parseFunc_RTE`
329 functionality is available.
330
331 You can check if this TypoScript snippet is loaded by using
332 :guilabel:`Web > Template` and use the TypoScript Object Browser (Setup)
333 to see if :typoscript:`lib.parseFunc_RTE` is filled.
334
335 .. todo: [SCREENSHOT of TSOB having lib.parseFunc_RTE open]
336
337 .. important::
338 Take care of where you add opening and closing tags, if you don't use the fluid inline notation.
339 If they are on an own line, the rendered output includes empty paragraphs at beginning and end.