[BUGFIX] Fix PageTS config example of CKEditor RTE
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.6 / Feature-79440-FormEngineElementExpansion.rst
1 .. include:: ../../Includes.txt
2
3 ==================================================
4 Deprecation: #79440 - FormEngine Element Expansion
5 ==================================================
6
7 See :issue:`79440`
8
9 Description
10 ===========
11
12 A new API in FormEngine has been introduced that allows fine grained additions to
13 single elements and containers without substituting the whole element.
14
15 For elements within the :code:`TCA` config section, three new options have been introduced:
16
17 * :code:`fieldInformation` An array of single field information. This could be additionally describing text
18   that is rendered between the element label and the element itself. Field information are restricted, only
19   a couple of HTML tags are allowed within the result HTML.
20 * :code:`fieldControl` An array of single field controls. These are icons with JavaScript or
21   links to further functionality of the framework. They are usually displayed next to the element. Each control
22   must return an icon identifier, a title, and an array of a-tag attributes.
23 * :code:`fieldWizard` Additional functionality enriching the element. These are typically shown
24   below the element. Wizards may return any HTML.
25
26 For FormEngine containers, the same API has been introduced, but it is currently only implemented within
27 the :code:`OuterWrapContainer` which renders the record title and delegates the main record rendering to
28 a different container. Adding :code:`fieldInformation` or :code:`fieldWizard` here allows embedding additional
29 functionality between the record title an the main record body.
30
31 Single elements and containers may register default information, control and wizards. The configuration is merged
32 with any possibly given configuration from `TCA`.
33
34 Example from :code:`GroupElement`:
35
36 .. code-block:: php
37
38     class GroupElement extends AbstractFormElement
39     {
40         /**
41          * Default field controls for this element.
42          *
43          * @var array
44          */
45         protected $defaultFieldControl = [
46             'elementBrowser' => [
47                 'renderType' => 'elementBrowser',
48             ],
49             'insertClipboard' => [
50                 'renderType' => 'insertClipboard',
51                 'after' => [ 'elementBrowser' ],
52             ],
53             'editPopup' => [
54                 'renderType' => 'editPopup',
55                 'disabled' => true,
56                 'after' => [ 'insertClipboard' ],
57             ],
58             'addRecord' => [
59                 'renderType' => 'addRecord',
60                 'disabled' => true,
61                 'after' => [ 'editPopup' ],
62             ],
63             'listModule' => [
64                 'renderType' => 'listModule',
65                 'disabled' => true,
66                 'after' => [ 'addRecord' ],
67             ],
68         ];
69
70         public function render()
71         {
72             ...
73             $fieldControlResult = $this->renderFieldControl();
74             $fieldControlHtml = $legacyFieldControlHtml . $fieldControlResult['html'];
75             $resultArray = $this->mergeChildReturnIntoExistingResult($resultArray, $fieldControlResult, false);
76         }
77     }
78
79 This element registers five default field controls (icons next to the element), renders them and later
80 adds the HTML at an appropriate place within the HTML of the main element. The :code:`defaultFieldControl` can
81 be overwritten on :code:`TCA` level of single fields:
82
83 .. code-block:: php
84
85     'columns' => [
86         'aField' => [
87             'label' => 'aField',
88             'config' => [
89                 'fieldControl' => [
90                     'elementBrowser' => [
91                         'disabled' => true,
92                     ],
93                     'editPopup' => [
94                         'disabled' => false,
95                     ],
96                     'aNewControl' => [
97                         'renderType' => 'myOwnTypeGroupControl',
98                         'before' => [ 'elementBrowser' ],
99                     ],
100                 ],
101             ],
102         ],
103     ],
104
105
106 The above configuration disables the element browser which is enabled by default, it enabled the edit popup
107 control which exists in default configuration but is disabled by default, and it adds a further control called
108 :code:`aNewControl` with :code:`renderType=myOwnTypeGroupControl`. The renderType instructs the FormEngine
109 :code:`NodeFactory` to instantiate the class that in configured for that renderType, identical to other usages
110 of the NodeFactory, this lookup can be manipulated on configuration and code level. In the example above, a new
111 renderType should be registered in :code:`ext_localconf.php`:
112
113 .. code-block:: php
114
115     $GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['nodeRegistry'][1485351217] = [
116         'nodeName' => 'myOwnTypeGroupControl',
117         'priority' => 30,
118         'class' => \My\ExtensionName\Form\FieldControl\MyFancyControl::class,
119     ];
120
121
122 Note the above configuration also uses the :code:`DependencyResolver`: It is possible to resort single
123 elements by adding :code:`before` and :code:`after` to the configuration. In above example, the new
124 control :code:`aNewControl` would be shown as first control, before :code:`elementBrowser`.
125
126 The first level below :code:`fieldControl` contains speaking names of single controls, each control must
127 have a :code:`renderType` defined (either on TCA level or via defaultFieldControl), and they may have
128 a :code:`before` and :code:`after` and a :code:`disabled` setting. Each control also may have a :code:`options`
129 sub array with further settings given to the specific control.
130
131 In :code:`TCA`, the configuration name for field controls is :code:`fieldControl`, for wizards it is :code:`fieldWizard`,
132 and for information it is :code:`fieldInformation`. All three follow the same structure. It is up to a single element
133 if all three of these are actually called and rendered. For instance, it sometimes does not make sense to have
134 field controls in all elements, so some elements skip that.
135
136 For containers, the configuration of :code:`fieldInformation`, :code:`fieldControl` and :code:`fieldWizard` is within
137 the :code:`ctrl` section of :code:`TCA`. This is currently only implemented within the :code:`OuterWrapContainer` for
138 :code:`fieldInformation` and :code:`fieldWizard`.
139
140 Example:
141
142 .. code-block:: php
143
144     'ctrl' => [
145         ...
146         'container' => [
147             'outerWrapContainer' => [
148                 'fieldInformation' => [
149                     'myHelloWorld' => [
150                         'renderType' => 'helloWorld',
151                     ],
152                 ],
153             ],
154         ],
155     ],
156
157
158 The above example would instruct the system to call the class registered for renderType :code:`helloWorld`
159 within the OuterWrapContainer.
160
161
162 Impact
163 ======
164
165 The new API brings lots of new options to add functionality to single elements
166 without substituting the full element.
167
168
169 .. index:: Backend, TCA