[BUGFIX] Fix PageTS config example of CKEditor RTE
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.6 / Deprecation-79440-TcaChanges.rst
1 .. include:: ../../Includes.txt
2
3 =================================
4 Deprecation: #79440 - TCA Changes
5 =================================
6
7 See :issue:`79440`
8
9 Description
10 ===========
11
12 The :code:`TCA` on field level has been changed. Nearly all column types are affected.
13 In general, the sub-section :code:`wizards` is gone and replaced by a combination of new
14 :code:`renderType`s and a new set of configuration options. Wizards are now divided into
15 three different kinds:
16
17 * :code:`fieldInformation` - Informational HTML, typically displayed between the element label
18   and the element itself.
19 * :code:`fieldControl` - Icons, typically displayed right next to the element, used to trigger
20   certain actions, for instance to jump to the link view.
21 * :code:`fieldWizard` - HTML typically shown below the element to enrich the element with further
22   functionality. Example is the rendering of thumbnails below a type=group element.
23
24 Other wizards like the "suggest" functionality have been merged into the affected elements itself.
25
26 Additionally, the config option :code:`defaultExtras`, which was often set within :code:`columnsOverrides` has
27 been removed. The options were transferred to config options of the elements itself and can be set
28 within :code:`columnsOverrides` directly.
29
30 A :code:`TCA` migration transforms old configuration options to new ones and throws descriptive log entries.
31
32 The first list covers all former existing wizards and shows where and how the functionality is now placed.
33
34 The second list below gives examples from before and after based on :code:`type`, together with detail
35 information on certain configuration options.
36
37
38 Wizard list
39 -----------
40
41
42 Add wizard, edit wizard and list wizard
43 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
44
45 The three wizards :code:`wizard_add`, :code:`wizard_edit` and :code:`wizard_list` usually used in :code:`type=group`
46 and :code:`type=select` with :code:`renderType=selectMultipleSideBySide` are now default controls of these two elements
47 and just need to be enabled. :code:`options` are optional, the render engine selects a fallback title, a default pid and
48 table name if needed.
49
50 Example before:
51
52 .. code-block:: php
53
54     'wizards' => [
55         '_VERTICAL' => 1,
56         'edit' => [
57             'type' => 'popup',
58             'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_tca.xlf:be_users.usergroup_edit_title',
59             'module' => [
60                 'name' => 'wizard_edit',
61             'popup_onlyOpenIfSelected' => true,
62             'icon' => 'actions-open',
63             'JSopenParams' => 'width=800,height=600,status=0,menubar=0,scrollbars=1'
64         ],
65         'add' => [
66             'type' => 'script',
67             'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_tca.xlf:be_users.usergroup_add_title',
68             'icon' => 'actions-add',
69             'params' => [
70                 'table' => 'be_groups',
71                 'pid' => 0,
72                 'setValue' => 'prepend'
73             ],
74             'module' => [
75                 'name' => 'wizard_add'
76             ]
77         ],
78         'list' => [
79             'type' => 'script',
80             'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_tca.xlf:be_users.usergroup_list_title',
81             'icon' => 'actions-system-list-open',
82             'params' => [
83                 'table' => 'be_groups',
84                 'pid' => 0
85             ],
86             'module' => [
87                 'name' => 'wizard_list'
88             ]
89         ]
90     ]
91
92
93 Example after:
94
95 .. code-block:: php
96
97     'fieldControl' => [
98         'editPopup' => [
99             'disabled' => false,
100         ],
101         'addRecord' => [
102             'disabled' => false,
103             'options' => [
104                 'setValue' => 'prepend',
105             ],
106         'listModule' => [
107             'disabled' => false,
108         ],
109     ],
110
111
112 Color picker
113 ^^^^^^^^^^^^
114
115 The color picker wizard has been changed to :code:`type=input` element with :code:`renderType=colorpicker`
116
117 Example before:
118
119 .. code-block:: php
120
121     'input_34' => [
122         'label' => 'input_34',
123         'config' => [
124             'type' => 'input',
125             'wizards' => [
126                 'colorChoice' => [
127                    'type' => 'colorbox',
128                    'title' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.colorPick',
129                    'module' => [
130                       'name' => 'wizard_colorpicker',
131                    ],
132                    'JSopenParams' => 'height=600,width=380,status=0,menubar=0,scrollbars=1',
133                    'exampleImg' => 'EXT:examples/res/images/japanese_garden.jpg',
134                 ]
135             ],
136         ],
137     ],
138
139
140 Example after:
141
142 .. code-block:: php
143
144     'input_34' => [
145         'label' => 'input_34',
146         'config' => [
147             'type' => 'input',
148             'renderType' => 'colorpicker',
149         ],
150     ],
151
152
153 Table wizard
154 ^^^^^^^^^^^^
155
156 The table wizard has been embedded in :code:`type=text` element with :code:`renderType=textTable`
157
158 Example before:
159
160 .. code-block:: php
161
162     'text_17' => [
163         'label' => 'text_17',
164         'config' => [
165             'type' => 'text',
166             'cols' => '40',
167             'rows' => '5',
168             'wizards' => [
169                 'table' => [
170                     'notNewRecords' => 1,
171                     'type' => 'script',
172                     'title' => 'LLL:EXT:cms/locallang_ttc.xlf:bodytext.W.table',
173                     'icon' => 'content-table',
174                     'module' => [
175                         'name' => 'wizard_table'
176                     ],
177                     'params' => [
178                         'xmlOutput' => 0
179                     ]
180                 ],
181             ],
182         ],
183     ],
184
185
186 Example after:
187
188 .. code-block:: php
189
190     'text_17' => [
191         'label' => 'text_17',
192         'config' => [
193             'type' => 'text',
194             'renderType' => 'textTable',
195             'cols' => '40',
196             'rows' => '5',
197         ],
198     ],
199
200
201 RTE wizard
202 ^^^^^^^^^^
203
204 The RTE wizard that jumps to a full screen view of a text field has been embedded into `EXT:rtehtmlarea`
205 directly and just needs to be turned on. This additionally obsoletes the :code:`defaultExtras=rte_only` setting.
206
207 Example before:
208
209 .. code-block:: php
210
211     'rte_1' => [
212         'label' => 'rte_1',
213         'config' => [
214             'type' => 'text',
215             'enableRichtext' => true,
216             'RTE' => [
217                 'notNewRecords' => 1,
218                 'RTEonly' => 1,
219                 'type' => 'script',
220                 'title' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:bodytext.W.RTE',
221                 'icon' => 'actions-wizard-rte',
222                 'module' => [
223                     'name' => 'wizard_rte'
224                 ]
225             ],
226         ],
227     ],
228
229
230 Example after:
231
232 .. code-block:: php
233
234     'rte_1' => [
235         'label' => 'rte_1',
236         'config' => [
237             'type' => 'text',
238             'enableRichtext' => true,
239             'fieldControl' => [
240                 'fullScreenRichtext' => [
241                     'disabled' => false,
242                 ],
243             ],
244         ],
245     ],
246
247
248 Link browser
249 ^^^^^^^^^^^^
250
251 The link browser icon wizard has been embedded in new :code:renderType=`inputLink` directly. The parameters
252 :code:`blindLinkOptions`, :code:`blindLinkFields` and :code:`allowedExtensions` are now all optional and options of
253 section :code:`fieldControl`.
254
255 Example before:
256
257 .. code-block:: php
258
259     'input_29' => [
260         'label' => 'input_29 link',
261         'config' => [
262             'type' => 'input',
263             'wizards' => [
264                 'link' => [
265                 'type' => 'popup',
266                 'title' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:header_link_formlabel',
267                 'icon' => 'actions-wizard-link',
268                 'module' => [
269                    'name' => 'wizard_link',
270                 ],
271                 'JSopenParams' => 'height=800,width=600,status=0,menubar=0,scrollbars=1',
272                 'params' => [
273                     'blindLinkOptions' => 'folder',
274                     'blindLinkFields' => 'class, target',
275                     'allowedExtensions' => 'jpg',
276                 ],
277             ],
278         ],
279     ],
280
281
282 Example after:
283
284 .. code-block:: php
285
286     'input_29' => [
287         'label' => 'input_29',
288         'config' => [
289             'type' => 'input',
290             'renderType' => 'inputLink',
291             'fieldControl' => [
292                 'linkPopup' => [
293                     'options' => [
294                         'blindLinkOptions' => 'folder',
295                         'blindLinkFields' => 'class, target',
296                         'allowedExtensions' => 'jpg',
297                     ],
298                 ],
299             ],
300         ],
301     ],
302
303
304 Select wizard
305 ^^^^^^^^^^^^^
306
307 The select wizard has been directly embedded in :code:`type=input` and :code:`type=text` elements, only works with
308 a static list of items and is called :code:`valuePicker`.
309
310 Example before:
311
312 .. code-block:: php
313
314     'input_33' => [
315         'label' => 'input_33',
316         'config' => [
317             'type' => 'input',
318             'wizards' => [
319                 'select' => [
320                     'items' => [
321                         [ 'spring', 'Spring', ],
322                         [ 'summer', 'Summer', ],
323                         [ 'autumn', 'Autumn', ],
324                         [ 'winter', 'Winter', ],
325                     ],
326                 ],
327             ],
328         ],
329     ],
330
331
332
333 Example after:
334
335 .. code-block:: php
336
337     'input_33' => [
338         'label' => 'input_33',
339         'config' => [
340             'type' => 'input',
341             'valuePicker' => [
342                 'items' => [
343                     [ 'spring', 'Spring', ],
344                     [ 'summer', 'Summer', ],
345                     [ 'autumn', 'Autumn', ],
346                     [ 'winter', 'Winter', ],
347                 ],
348             ],
349         ],
350     ],
351
352
353 Suggest wizard
354 ^^^^^^^^^^^^^^
355
356 The suggest wizard has been directly embedded in :code:`type=group` element and is enabled by default. It
357 can be disabled by setting :code:`hideSuggest=true` in config section and suggest options can be added in
358 :code:`suggestOptions`.
359
360 Example before:
361
362 .. code-block:: php
363
364     'group_db_8' => [
365         'label' => 'group_db_8',
366         'config' => [
367             'type' => 'group',
368             'internal_type' => 'db',
369             'allowed' => 'tx_styleguide_staticdata',
370             'wizards' => [
371                 '_POSITION' => 'top',
372                     'suggest' => [
373                         'type' => 'suggest',
374                         'default' => [
375                             'pidList' => 42,
376                         ],
377                     ],
378                 ],
379             ],
380         ],
381     ],
382
383
384 Example after:
385
386 .. code-block:: php
387
388     'group_db_8' => [
389         'label' => 'group_db_8',
390         'config' => [
391             'type' => 'group',
392             'internal_type' => 'db',
393             'allowed' => 'tx_styleguide_staticdata',
394             'suggestOptions' => [
395                 'default' => [
396                     'pidList' => 42,
397                 ]
398             ],
399         ],
400     ],
401
402
403 Slider wizard
404 ^^^^^^^^^^^^^
405
406 The slider wizard has been embedded in :code:`type=text` as option :code:`slider` within the
407 config section.
408
409 Example before:
410
411 .. code-block:: php
412
413     'input_30' => [
414         'label' => 'input_30',
415         'config' => [
416             'type' => 'input',
417             'size' => 5,
418             'eval' => 'trim,int',
419             'range' => [
420                 'lower' => -90,
421                 'upper' => 90,
422             ],
423             'default' => 0,
424             'wizards' => [
425                 'angle' => [
426                     'type' => 'slider',
427                     'step' => 10,
428                     'width' => 200,
429                 ],
430             ],
431         ],
432     ],
433
434
435 Example after:
436
437 .. code-block:: php
438
439     'input_30' => [
440         'label' => 'input_30',
441         'config' => [
442             'type' => 'input',
443             'size' => 5,
444             'eval' => 'trim,int',
445             'range' => [
446                 'lower' => -90,
447                 'upper' => 90,
448             ],
449             'default' => 0,
450             'slider' => [
451                 'step' => 10,
452                 'width' => 200,
453             ],
454         ],
455     ],
456
457
458
459 Type list
460 ---------
461
462 type=input
463 ^^^^^^^^^^
464
465 * The wizard :code:`slider` has been directly embedded in this element. The new config option :code:`slider`
466   can be used to configure the slider. The slider appears if the option :code:`slider` exists and is an arary.
467 * The wizard :code:`select` has been directly embedded in this element. The new config option :code:`valuePicker`
468   has been introduced to configure items of the drop down.
469 * The four date related :code:`eval` options :code:`date`, :code:`datetime`, :code:`time` and :code:`timesec` have
470   been moved to :code:`renderType=inputDateTime`.
471 * The wizard :code:`wizard_link` has been removed a field now displays the link wizard by setting :code:`renderType=inputLink`
472   for a :code:`type=input` element.
473
474
475 type=text
476 ^^^^^^^^^
477
478 * The wizard :code:`select` has been directly embedded in this element. The new config option :code:`valuePicker`
479   has been introduced to configure items of the drop down.
480 * The wizard :code:`wizard_table` has been given the own :code:`renderType=textTable`.
481 * The wizard :code:`RTE` has been changed to a `fieldControl` of the richtext element implemented by
482   extension `rtehtmlarea`.
483 * :code:`defaultExtras=enable-tab` has been moved to config option :code:`enableTabulator`
484 * :code:`defaultExtrasfixed-font` has been moved to config option :code:`fixedFont`
485 * :code:`defaultExtras=nowrap` has been moved to config option :code:`wrap=off`
486
487
488 type=select with renderType=selectSingle
489 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
490
491 * Config option :code:`showIconTable` has been dropped. Showing assigned images below the select field has
492   been migrated to a :code:`fieldWizard` and is disabled by default.
493 * Config option :code:`selicon_cols` has been dropped without substitution, the render engine now shows as
494   many images in a row as fit into the view.
495
496 Example to enable the icon display:
497
498 .. code-block:: php
499
500     'select_single_5' => [
501         'label' => 'select_single_5',
502         'config' => [
503             'type' => 'select',
504             'renderType' => 'selectSingle',
505             'items' => [
506                 ['foo 1', 'foo1', 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg'],
507                 ['foo 2', 'foo2', 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg'],
508             ],
509             'fieldWizard' => [
510                 'selectIcons' => [
511                     'disabled' => false,
512                 ],
513             ],
514         ],
515     ],
516
517
518 type=select with renderType=multipleSideBySide
519 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
520
521 Configuration option changes of the :code:`renderType=multipleSideBySide` element are similar to
522 the :code:`type=group` changes. In detail, the following changes have been applied:
523
524 * Config option :code:`selectedListStyle` has been dropped without substitution.
525 * Wizards :code:`wizard_add`, :code:`wizard_edit` and :code:`wizard_list` have been changed to :code:`fieldControl`
526   and must be enabled per element. All options are still valid, but the system tries to determine sane fallback
527   values if no options are given. For example, the `table` option of :code:`wizard_add` and :code:`wizard_list`
528   fall back to the value of :code:`foreign_table` if not explicitly given.
529
530 Example configuration of a multipleSideBySide field before change:
531
532 .. code-block:: php
533
534     'select_multiplesidebyside_6' => [
535         'exclude' => 1,
536         'label' => 'select_multiplesidebyside_6',
537         'config' => [
538             'type' => 'select',
539             'renderType' => 'selectMultipleSideBySide',
540             'foreign_table' => 'tx_styleguide_staticdata',
541             'rootLevel' => 1,
542             'size' => 5,
543             'autoSizeMax' => 20,
544             'wizards' => [
545                 '_VERTICAL' => 1,
546                 'edit' => [
547                     'type' => 'popup',
548                     'title' => 'edit',
549                     'module' => [
550                         'name' => 'wizard_edit',
551                     ],
552                     'icon' => 'actions-open',
553                     'popup_onlyOpenIfSelected' => 1,
554                     'JSopenParams' => 'height=350,width=580,status=0,menubar=0,scrollbars=1',
555                 ],
556                 'add' => [
557                     'type' => 'script',
558                     'title' => 'add',
559                     'icon' => 'actions-add',
560                     'module' => [
561                         'name' => 'wizard_add',
562                     ],
563                     'params' => [
564                         'table' => 'tx_styleguide_staticdata',
565                         'pid' => '0',
566                         'setValue' => 'prepend',
567                     ],
568                 ],
569                 'list' => [
570                     'type' => 'script',
571                     'title' => 'list',
572                     'icon' => 'actions-system-list-open',
573                     'module' => [
574                         'name' => 'wizard_list',
575                     ],
576                     'params' => [
577                         'table' => 'tx_styleguide_staticdata',
578                         'pid' => '0',
579                     ],
580                 ],
581             ],
582         ],
583     ],
584
585
586 Example after:
587
588 .. code-block:: php
589
590      'select_multiplesidebyside_6' => [
591          'exclude' => 1,
592          'label' => 'select_multiplesidebyside_6 wizards',
593          'config' => [
594              'type' => 'select',
595              'renderType' => 'selectMultipleSideBySide',
596              'foreign_table' => 'tx_styleguide_staticdata',
597              'rootLevel' => 1,
598              'size' => 5,
599              'autoSizeMax' => 20,
600              'fieldControls' => [
601                  'editPopup' => [
602                      'disabled' => false,
603                  ],
604                  'addRecord' => [
605                      'disabled' => false,
606                  ],
607                  'listModule' => [
608                      'disabled' => false,
609                  ],
610              ],
611          ],
612      ],
613
614
615 type=group
616 ^^^^^^^^^^
617
618 This element got most changes in this series. A number of options have been fine-tuned
619 and got better default values:
620
621 * Similar to :code:`type=select` with :code:`type=multipleSideBySide`, the three wizards
622   :code:`wizard_add`, :code:`wizard_edit` and :code:`wizard_list` have been changed to :code:`fieldControl`
623   and are disabled by default.
624 * Config option :code:`selectedListStyle` has been dropped without substitution.
625 * The suggest wizard has been directly embedded in :code:`type=group` and has been enabled by default for
626   :code:`internal_type=db` elements. It can be disabled with :code:`hideSuggest=true` and options of the
627   `suggest` can be hand over in config option :code:`suggestOptions`.
628 * The config option :code:`show_thumbs` showed two different things in the past: With :code:`internal_type=db`, it
629   displayed the list of selected records as a table below the element, with :code:`internal_type=file` it rendered
630   thumbnails of selected files and displayed the below the element. :code:`show_thumbs` has been dropped, the
631   functionality has been transferred to :code:`fieldWizard` as :code:`recordsOverview` and :code:`fileThumbnails`
632   respectively and are enabled by default. They can be disabled by setting `disabled=true`.
633 * The config option :code:`disable_controls` has been obsoleted, single parts of the group element can be disabled
634   by adding :code:`disabled=true` to the according :code:`fieldControl` or :code:`fieldWizard`.
635
636
637 Example of a typical group field before:
638
639 .. code-block:: php
640
641     'group_db_1' => [
642         'label' => 'group_db_1',
643         'config' => [
644             'type' => 'group',
645             'internal_type' => 'db',
646             'allowed' => 'be_users,be_groups',
647             'wizards' => [
648                 'edit' => [
649                     'type' => 'popup',
650                     'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.edit',
651                     'module' => [
652                         'name' => 'wizard_edit',
653                     ],
654                     'popup_onlyOpenIfSelected' => 1,
655                     'icon' => 'actions-open',
656                     'JSopenParams' => 'height=350,width=580,status=0,menubar=0,scrollbars=1'
657                 ],
658                 'add' => [
659                     'type' => 'script',
660                     'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.createNewPage',
661                     'icon' => 'actions-add',
662                     'params' => [
663                         'table' => 'be_users',
664                         'pid' => 0,
665                         'setValue' => 'append'
666                     ],
667                     'module' => [
668                     'name' => 'wizard_add'
669                     ],
670                 ],
671                 'list' => [
672                     'type' => 'script',
673                     'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.list',
674                     'icon' => 'actions-system-list-open',
675                     'params' => [
676                         'table' => 'be_groups',
677                         'pid' => '0'
678                     ],
679                     'module' => [
680                         'name' => 'wizard_list'
681                     ]
682                 ]
683             ],
684         ],
685     ],
686
687
688 Example after:
689
690 .. code-block:: php
691
692     'group_db_1' => [
693         'label' => 'group_db_1',
694         'config' => [
695             'type' => 'group',
696             'internal_type' => 'db',
697             'allowed' => 'be_users,be_groups',
698             'fieldControls' => [
699                 'editPopup' => [
700                     'disabled' => false,
701                 ],
702                 'addRecord' => [
703                     'disabled' => false,
704                 ],
705                 'listModule' => [
706                     'renderType' => 'listModule',
707                     'options' => [
708                     'disabled' => false,
709                 ],
710             ],
711         ],
712     ],
713
714
715 Disable other parts of type=group:
716
717     'group_db_1' => [
718         'label' => 'group_db_1',
719         'config' => [
720             'type' => 'group',
721             'internal_type' => 'db',
722             'allowed' => 'be_users,be_groups',
723             'fieldControl' => [
724                 // Disable element browser icon
725                 'elementBrowser' => [
726                     'disabled' => true,
727                 ],
728                 // Disable insert from clipboard icon
729                 'insertClipboard' => [
730                     'disabled' => true,
731                 ],
732             ],
733             'fieldWizard => [
734                 // Disable button list of allowed tables
735                 'tableList' => [
736                     'disabled' => true,
737                 ],
738                 // Disable list of allowed file types
739                 'fileTypeList' => [
740                     'disabled' => true,
741                 ],
742                 // Disable thumbnail view of selected files
743                 'fileThumbnails' => [
744                     'disabled' => true,
745                 ],
746                 // Disable table view of selected records
747                 'recordsOverview' => [
748                     'disabled' => true,
749                 ],
750                 // Disable direct file upload button
751                 'fileUpload' => [
752                     'disabled' => true,
753                 ],
754             ],
755         ],
756     ],
757
758
759 Impact
760 ======
761
762 Using old TCA settings as outlined above will throw a deprecation warnings.
763
764
765 Affected Installations
766 ======================
767
768 Most installations are affected by this change.
769
770
771 Migration
772 =========
773
774 An automatic TCA migration transfers from old TCA settings to new ones and throws deprecation log entries with
775 hints which changes should be incorporated. For flex form data structure definitions, the TCA migration is called
776 when opening an according record and logs, too.
777
778 .. index:: Backend, TCA