Breaking: #79464 - EXT:form - Refactor fluid rendering

See forge#79464

Description

EXT:form uses "fluid" as the default rendering strategy. Therefore, EXT:form has to work closely with the concepts of fluid to avoid current and future problems. 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. This change reduces the complexity of the rendering process and works closer with the concepts of fluid.

Impact

The configuration options renderingOptions.templateRootPaths, renderingOptions.partialRootPaths and renderingOptions.layoutRootPaths for form elements are from now on only rules for the root form element ('Form') and will be applied for all child form elements. If you configure renderingOptions.templateRootPaths etc. for other form elements it will have no effect.

The configuration option renderingOptions.templatePathAndFilename for form elements was removed from the configuration and will have no effect. 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.

The internal setting renderingOptions.renderableNameInTemplate for form elements has been removed from the configuration and will have no effect.

The setting rendererClassName for form elements are from now on only rules for the root form element ('Form'). If you define this option for other form elements, an invalid configuration exception will be thrown.

The configuration for the backend editor inline templates which are used by editor javascript has changed. The configuration path prototypes.<prototypeName>.formEditor.formEditorTemplates has been renamed and has no effect anymore. The fluid configuration part moved from prototypes.<prototypeName>.formEditor.formEditorTemplates to a new section prototypes.<prototypeName>.formEditor.formEditorFluidConfiguration. The backend editor inline template mapping moved to a new section prototypes.<prototypeName>.formEditor.formEditorPartials. 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 result in a javascript error within the form editor.

The template files moved from Resources/Private/Frontend/Templates/FormElements/ to Resources/Private/Frontend/Partials. The template structure has changed. Without adaptation of your overridden templates, no form elements are visible within the frontend.

Affected Installations

All installations since TYPO3 8.5 which use the new EXT:form extension and create or extend custom form elements through configuration and / or override EXT:form template files.

Migration

If you override/ extend

TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.templateRootPaths
TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.partialRootPaths
TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.layoutRootPaths

move it to

TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.templateRootPaths
TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.partialRootPaths
TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.layoutRootPaths

If you override/ extend

TYPO3.CMS.Form.mixins.formElementMixins.BaseFormElementMixin.renderingOptions.skipUnknownElements

move it to

TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.skipUnknownElements

If you defined

TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.<formElementType>.rendererClassName

for a <formElementType> which is NOT 'Form', you have to remove this setting.

If you defined

TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.renderableNameInTemplate

you have to use

TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.templateName

templateName is the partial path, relative to TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.partialRootPaths

If you defined custom form editor templates within

TYPO3.CMS.Form.prototypes.<prototypeName>.formEditor.formEditorTemplates

you have to move this to

TYPO3.CMS.Form.prototypes.<prototypeName>.formEditor.formEditorPartials

If you defined a custom form editor stage template which depends on a default form editor stage template you have to redefine it:

Stage/Text => Stage/SimpleTemplate
Stage/Password => Stage/SimpleTemplate
Stage/AdvancedPassword => Stage/SimpleTemplate
Stage/Textarea => Stage/SimpleTemplate
Stage/Checkbox => Stage/SimpleTemplate
Stage/MultiCheckbox => Stage/SelectTemplate
Stage/MultiSelect => Stage/SelectTemplate
Stage/RadioButton => Stage/SelectTemplate
Stage/SingleSelect => Stage/SelectTemplate
Stage/DatePicker => Stage/SimpleTemplate
Stage/Hidden => Stage/SimpleTemplate
Stage/FileUpload => Stage/FileUploadTemplate
Stage/ImageUpload => Stage/FileUploadTemplate

All form element templates except the template for the Form element moved from templates to partials. You have to move this too, if you extended the fluid search paths. The 'Form' element is a template and will be found through TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.templateRootPaths. All other form elements are partials and will be found through TYPO3.CMS.Form.prototypes.<prototypeName>.formElementsDefinition.Form.renderingOptions.partialRootPaths.

The template/partial structure has changed. You have to adapt this to your custom templates. Please look at the files within EXT:form/Resources/Private/Frontend/Partials to see what has happened. The main change is that you have to wrap the markup with

<formvh:renderRenderable renderable="{element}">
    some form element
</formvh:renderRenderable>