Configuring form rendering with YAML¶
Setup¶
To render a form based on a YAML configuration file, simply use the Neos.Form render
ViewHelper.
It uses the Neos\Form\Factory\ArrayFormFactory
by default, which needs to know where the form
configuration is stored. This is done in Settings.yaml
:
Neos:
Form:
yamlPersistenceManager:
savePath: 'resource://AcmeCom.SomePackage/Private/Form/'
From now on, every YAML file stored there can be loaded by using the filename as the persistence
identifier given to the render
ViewHelper. So if you have a file named contact.yaml
, it
can be rendered with:
<form:render persistenceIdentifier="contact"/>
Form configuration¶
Generally speaking, the configuration is a nested structure that contains the keys type
, identifier
and
renderables
and further options (e.g. label
) depending on the type of the current level.
The element types referenced below (Neos.Form:SingleLineText
and Neos.Form:MultiLineText
)
are just element types which are delivered by default by the framework. All available types can be
found in the settings of the Neos.Form package under Neos.Form.presets.default.formElementTypes
.
On the top level, the finishers
can be configured as an array of identifier
and options
keys. The
available options depend on the finisher being used.
Let us examine the configuration for a basic contact form with the following structure:
- Contact Form (Form)
- Page 01 (Page)
- Name (Single-line Text)
- Email (Single-line Text)
- Message (Multi-line Text)
The following YAML is stored as contact.yaml
:
type: 'Neos.Form:Form'
identifier: 'contact'
label: 'Contact form'
renderables:
-
type: 'Neos.Form:Page'
identifier: 'page-one'
renderables:
-
type: 'Neos.Form:SingleLineText'
identifier: name
label: 'Name'
validators:
- identifier: 'Neos.Flow:NotEmpty'
-
type: 'Neos.Form:SingleLineText'
identifier: email
label: 'Email'
validators:
- identifier: 'Neos.Flow:NotEmpty'
- identifier: 'Neos.Flow:EmailAddress'
-
type: 'Neos.Form:MultiLineText'
identifier: message
label: 'Message'
validators:
- identifier: 'Neos.Flow:NotEmpty'
finishers:
-
identifier: 'Neos.Form:Email'
options:
templatePathAndFilename: resource://AcmeCom.SomePackage/Private/Templates/Form/Contact.txt
subject: '{subject}'
recipientAddress: 'info@acme.com'
recipientName: 'Acme Customer Care'
senderAddress: '{email}'
senderName: '{name}'
format: plaintext
Note
Instead of setting the templatePathAndFilename
option to specify the Fluid template file for the EmailFinisher,
the template source can also be set directly via the templateSource
option.
File Uploads¶
The default
preset comes with an FileUpload
form element that allows the user of the form to upload arbitrary
files.
The EmailFinisher
allows these files to be sent as attachments:
type: 'Neos.Form:Form'
identifier: 'application'
label: 'Example application form'
renderables:
-
type: 'Neos.Form:Page'
identifier: 'page-one'
renderables:
-
type: 'Neos.Form:SingleLineText'
identifier: email
label: 'Email'
validators:
- identifier: 'Neos.Flow:NotEmpty'
- identifier: 'Neos.Flow:EmailAddress'
-
type: 'Neos.Form:FileUpload'
identifier: applicationform
label: 'Application Form (PDF)'
properties:
allowedExtensions:
- pdf
validators:
- identifier: 'Neos.Flow:NotEmpty'
finishers:
-
# Application email that is sent to "customer care" with all uploaded files attached
identifier: 'Neos.Form:Email'
options:
templatePathAndFilename: 'resource://AcmeCom.SomePackage/Private/Form/EmailTemplates/Application.html'
subject: 'New Application'
recipientAddress: 'application@acme.com'
senderAddress: '{email}'
format: html
attachAllPersistentResources: true
-
# Confirmation email that is sent to the user with a static file attachment
identifier: 'Neos.Form:Email'
options:
templatePathAndFilename: 'resource://AcmeCom.SomePackage/Private/Form/EmailTemplates/Confirmation.html'
subject: 'Your Application'
recipientAddress: '{email}'
senderAddress: 'application@acme.com'
format: html
attachments:
- resource: 'resource://AcmeCom.SomePackage/Private/Form/EmailTemplates/Attachments/TermsAndConditions.pdf'
Note
attachments can also referenced via formElement paths explicitly, for example: - formElement: 'image-field.resource'