[TASK] Update 8.6 Documentation
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.6 / Breaking-79464-ExtFormRefactorFluidRendering.rst
1 .. include:: ../../Includes.txt
2
3 ======================================================
4 Breaking: #79464 - EXT:form - Refactor fluid rendering
5 ======================================================
6
7 See :issue:`79464`
8
9 Description
10 ===========
11
12 EXT:form uses "fluid" as the default rendering strategy.
13 Therefore, EXT:form has to work closely with the concepts of fluid to avoid current and future problems.
14 Until now, EXT:form tried to reuse a fluid view instance by reconfiguring the instance on each nesting level, but fluid is not intended for such a purpose.
15 This change reduces the complexity of the rendering process and works closer with the concepts of fluid.
16
17
18 Impact
19 ======
20
21 The configuration options `renderingOptions.templateRootPaths`, `renderingOptions.partialRootPaths` and `renderingOptions.layoutRootPaths` for form elements are
22 from now on only rules for the root form element ('Form') and will be applied for all child form elements.
23 If you configure `renderingOptions.templateRootPaths` etc. for other form elements it will have no effect.
24
25 The configuration option `renderingOptions.templatePathAndFilename` for form elements was removed from the configuration and will have no effect.
26 To define a template file name which should be used instead of a filename which is named like the form element type, there is a new option `renderingOptions.templateName`.
27
28 The internal setting `renderingOptions.renderableNameInTemplate` for form elements has been removed from the configuration and will have no effect.
29
30 The setting `rendererClassName` for form elements are from now on only rules for the root form element ('Form').
31 If you define this option for other form elements, an `invalid configuration` exception will be thrown.
32
33 The configuration for the backend editor inline templates which are used by editor javascript has changed.
34 The configuration path `prototypes.<prototypeName>.formEditor.formEditorTemplates` has been renamed and has no effect anymore.
35 The fluid configuration part moved from `prototypes.<prototypeName>.formEditor.formEditorTemplates` to a new section `prototypes.<prototypeName>.formEditor.formEditorFluidConfiguration`.
36 The backend editor inline template mapping moved to a new section `prototypes.<prototypeName>.formEditor.formEditorPartials`.
37 The inline template mapping for stage templates has been condensed. If you define custom form editor stage templates which use a default stage template it could
38 result in a javascript error within the form editor.
39
40 The template files moved from `Resources/Private/Frontend/Templates/FormElements/` to `Resources/Private/Frontend/Partials`.
41 The template structure has changed. Without adaptation of your overridden templates, no form elements are visible within the frontend.
42
43
44 Affected Installations
45 ======================
46
47 All installations since TYPO3 8.5 which use the new EXT:form extension and create or extend custom form elements through configuration and / or
48 override EXT:form template files.
49
50
51 Migration
52 =========
53
54 If you override/ extend
55
56     `TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.templateRootPaths`
57     `TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.partialRootPaths`
58     `TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.layoutRootPaths`
59
60 move it to
61
62     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.templateRootPaths`
63     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.partialRootPaths`
64     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.layoutRootPaths`
65
66
67 If you override/ extend
68
69     `TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.skipUnknownElements`
70
71 move it to
72
73     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.skipUnknownElements`
74
75
76 If you defined
77
78     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.<formElementType>.rendererClassName`
79
80 for a <formElementType> which is *NOT* 'Form', you have to remove this setting.
81
82
83 If you defined
84
85     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.renderableNameInTemplate`
86
87 you have to use
88
89     `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.templateName`
90
91 `templateName` is the partial path, relative to `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.partialRootPaths`
92
93
94 If you defined custom form editor templates within
95
96     `TYPO3.CMS.Form.prototypes.<prototypeName>.formEditor.formEditorTemplates`
97
98 you have to move this to
99
100     `TYPO3.CMS.Form.prototypes.<prototypeName>.formEditor.formEditorPartials`
101
102
103 If you defined a custom form editor stage template which depends on a default form editor stage template you have to redefine it:
104
105     Stage/Text => Stage/SimpleTemplate
106     Stage/Password => Stage/SimpleTemplate
107     Stage/AdvancedPassword => Stage/SimpleTemplate
108     Stage/Textarea => Stage/SimpleTemplate
109     Stage/Checkbox => Stage/SimpleTemplate
110     Stage/MultiCheckbox => Stage/SelectTemplate
111     Stage/MultiSelect => Stage/SelectTemplate
112     Stage/RadioButton => Stage/SelectTemplate
113     Stage/SingleSelect => Stage/SelectTemplate
114     Stage/DatePicker => Stage/SimpleTemplate
115     Stage/Hidden => Stage/SimpleTemplate
116     Stage/FileUpload => Stage/FileUploadTemplate
117     Stage/ImageUpload => Stage/FileUploadTemplate
118
119
120 All form element templates except the template for the `Form` element moved from templates to partials.
121 You have to move this too, if you extended the fluid search paths.
122 The 'Form' element is a template and will be found through `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.templateRootPaths`.
123 All other form elements are partials and will be found through `TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.partialRootPaths`.
124
125
126 The template/partial structure has changed. You have to adapt this to your custom templates.
127 Please look at the files within `EXT:form/Resources/Private/Frontend/Partials`
128 to see what has happened.
129 The main change is that you have to wrap the markup with
130
131 .. code-block:: html
132
133     <formvh:renderRenderable renderable="{element}">
134         some form element
135     </formvh:renderRenderable>
136
137 .. index:: Backend, Frontend, ext:form