87067d040f9d6871903edc73af03a5fe4e9f33d9
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-82089-ExtFormSupportsYamlImports.rst
1 .. include:: ../../Includes.txt
2
3 ================================================
4 Feature: #82089 - EXT:form supports YAML imports
5 ================================================
6
7 See :issue:`82089`
8
9 Description
10 ===========
11
12 The `form` extension now features imports in YAML configuration files via the special toplevel
13 :yaml:`imports` option. With the help of this feature, form setup and especially form definitions
14 can be reused without copying.
15
16
17 Form setup configuration
18 ------------------------
19
20 The :yaml:`imports` option can now be used to load the form setup of the `form` extension followed
21 by a custom configuration.
22
23 For example a :file:`EXT:my_site_package/Configuration/Yaml/FormSetup.yaml` could look like this:
24
25 .. code-block:: yaml
26
27     imports:
28       - { resource: "EXT:form/Configuration/Yaml/FormSetup.yaml" }
29       - { resource: "EXT:my_site_package/Configuration/Yaml/FormSetup/Prototypes.yaml" }
30
31 You can also combine imports with configuration:
32
33 .. code-block:: yaml
34
35     imports:
36       - { resource: "EXT:form/Configuration/Yaml/FormSetup.yaml" }
37
38     TYPO3:
39       CMS:
40         Form:
41           prototypes:
42             # custom configuration
43             # ...
44
45
46 Form definitions
47 ----------------
48
49 Imports are also possible within form definitions but must be added manually to the YAML files.
50 Currently, the form editor does not have a graphical interface for imports.
51
52 The following example shows a basic contact form definition (e.g. in
53 :file:`fileadmin/form_definitions/contact.yaml`):
54
55 .. code-block:: yaml
56
57     identifier: contact
58     label: 'Contact us'
59     type: Form
60     prototypeName: standard
61     finishers:
62       EmailToReceiver:
63         identifier: EmailToReceiver
64         sorting: 10
65         options:
66           # ...
67     renderables:
68       page-1:
69         identifier: page-1
70         type: Page
71         sorting: 10
72         label: 'Contact Form'
73         renderables:
74           name:
75             identifier: name
76             type: Text
77             label: Name
78             sorting: 10
79             validators:
80               NotEmpty:
81                 identifier: NotEmpty
82                 sorting: 10
83           subject:
84             identifier: subject
85             type: Text
86             sorting: 20
87             label: Subject
88             validators:
89               NotEmpty:
90                 identifier: NotEmpty
91                 sorting: 10
92
93 Other form definitions can import :file:`fileadmin/form_definitions/contact.yaml` to inherit the
94 definitions. Additional form definitions can then be added to extend or change existing definitions.
95
96 .. important::
97
98    The form :yaml:`identifier` **must** be changed when importing other form definitions.
99
100 You have to do the following in oder to change the form label and to move the :yaml:`subject` field
101 before the :yaml:`name` field (see aforementioned
102 :file:`fileadmin/form_definitions/another-contact.yaml`):
103
104 .. code-block:: yaml
105
106     imports:
107       - { resource: fileadmin/form_definitions/contact.yaml }
108
109     # The identifier MUST be changed
110     identifier: inquiry
111
112     label: Inquiry
113     renderables:
114       page-1:
115         renderables:
116           name:
117             sorting: 20
118           subject:
119             sorting: 10
120
121 The key of every section with an :yaml:`identifier` property must be named exactly like the
122 :yaml:`identifier` property. This way it is ensured that form definitions importing other form
123 definitions and form definitions which are imported are properly merged.
124
125 For example, before this feature was introduced a list of :yaml:`finishers` was defined like this:
126
127 .. code-block:: yaml
128
129     finishers:
130       -
131         identifier: EmailToReceiver
132         options:
133           # ...
134       -
135         identifier: EmailToSender
136         options:
137           # ...
138       # ...
139
140 To guarantee imports work properly this must be rewritten slightly. Please use the :yaml:`identifier`
141 value as section key:
142
143 .. code-block:: yaml
144
145     finishers:
146       EmailToReceiver:
147         identifier: EmailToReceiver
148         options:
149           # ...
150       EmailToSender:
151         identifier: EmailToSender
152         options:
153           # ...
154       # ...
155
156 Aside from this, every section with an :yaml:`identifier` must have a :yaml:`sorting` property. This
157 property is essential to detect differences in sortings between the form definition you import and
158 the imported form definition.
159
160 .. tip::
161
162    Form definitions managed with the form editor are migrated automatically once opened and saved.
163
164
165 .. index:: Frontend, Backend, ext:form