FormDefinition extends AbstractCompositeRenderable implements VariableRenderableInterface
This class encapsulates a complete *Form Definition*, with all of its pages, form elements, validation rules which apply and finishers which should be executed when the form is completely filled in.
It is not modified when the form executes.
The Anatomy Of A Form
A FormDefinition consists of multiple Page () objects. When a form is displayed to the user, only one Page is visible at any given time, and there is a navigation to go back and forth between the pages.
A Page consists of multiple FormElements (, ), which represent the input fields, textareas, checkboxes shown inside the page.
FormDefinition, Page and FormElement have identifier properties, which must be unique for each given type (i.e. it is allowed that the FormDefinition and a FormElement have the same identifier, but two FormElements are not allowed to have the same identifier.
Simple Example
Generally, you can create a FormDefinition manually by just calling the API methods on it, or you use a Form Definition Factory to build the form from another representation format such as YAML.
/---code php $formDefinition = GeneralUtility::makeInstance(FormDefinition::class, 'myForm');
$page1 = GeneralUtility::makeInstance(Page::class, 'page1'); $formDefinition->addPage($page);
$element1 = GeneralUtility::makeInstance(GenericFormElement::class, 'title', 'Textfield'); # the second argument is the type of the form element $page1->addElement($element1); ---
Creating a Form, Using Abstract Form Element Types
While you can use the or methods and create the Page and FormElement objects manually, it is often better to use the corresponding create* methods ( and ), as you pass them an abstract Form Element Type such as Text or Page, and the system automatically resolves the implementation class name and sets default values.
So the simple example from above should be rewritten as follows:
/---code php $prototypeConfiguration = []; // We'll talk about this later
$formDefinition = GeneralUtility::makeInstance(FormDefinition::class, 'myForm', $prototypeConfiguration); $page1 = $formDefinition->createPage('page1'); $element1 = $page1->addElement('title', 'Textfield'); ---
Now, you might wonder how the system knows that the element Textfield is implemented using a GenericFormElement: This is configured in the $prototypeConfiguration.
To make the example from above actually work, we need to add some sensible values to $prototypeConfiguration:
$prototypeConfiguration = [ 'formElementsDefinition' => [ 'Page' => [ 'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\Page' ], 'Textfield' => [ 'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\GenericFormElement' ] ] ]
For each abstract Form Element Type we add some configuration; in the above case only the implementation class name. Still, it is possible to set defaults for all configuration options of such an element, as the following example shows:
$prototypeConfiguration = [ 'formElementsDefinition' => [ 'Page' => [ 'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\Page', 'label' => 'this is the label of the page if nothing is specified' ], 'Textfield' => [ 'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\GenericFormElement', 'label' = >'Default Label', 'defaultValue' => 'Default form element value', 'properties' => [ 'placeholder' => 'Text which is shown if element is empty' ] ] ] ]
Using Preconfigured $prototypeConfiguration
Often, it is not really useful to manually create the $prototypeConfiguration array.
Most of it comes pre-configured inside the YAML settings of the extensions, and the contains helper methods which return the ready-to-use $prototypeConfiguration.
Property Mapping and Validation Rules
Besides Pages and FormElements, the FormDefinition can contain information about the format of the data which is inputted into the form. This generally means:
- expected Data Types
- Property Mapping Configuration to be used
- Validation Rules which should apply
Background Info
You might wonder why Data Types and Validation Rules are not attached to each FormElement itself.
If the form should create a hierarchical output structure such as a multi- dimensional array or a PHP object, your expected data structure might look as follows:
- person -- firstName -- lastName -- address --- street --- city
Now, let's imagine you want to edit person.address.street and person.address.city, but want to validate that the combination of street and city is valid according to some address database.
In this case, the form elements would be configured to fill street and city, but the validator needs to be attached to the compound object address, as both parts need to be validated together.
Connecting FormElements to the output data structure
The identifier of the FormElement is most important, as it determines where in the output structure the value which is entered by the user is placed, and thus also determines which validation rules need to apply.
Using the above example, if you want to create a FormElement for the street, you should use the identifier person.address.street.
Rendering a FormDefinition
In order to trigger rendering on a FormDefinition, the current needs to be bound to the FormDefinition, resulting in a object which contains the Runtime State of the form (such as the currently inserted values).
/---code php
$currentRequest and $currentResponse need to be available, f.e. inside a controller you would
use $this->request. Inside a ViewHelper you would use $this->renderingContext->getRequest()
$form = $formDefinition->bind($currentRequest);
now, you can use the $form object to get information about the currently
entered values into the form, etc.
---
Refer to the API doc for further information.
Scope: frontend This class is NOT meant to be sub classed by developers.
May change any time, use FormFactoryInterface to select a different FormDefinition if needed
Tags
Table of Contents
Interfaces
- VariableRenderableInterface
- Scope: frontend **This class is NOT meant to be sub classed by developers.**
Properties
- $elementDefaultValues : array<string, mixed>
- Form element default values in the format ['elementIdentifier' => 'default value']
- $elementsByIdentifier : array<string, FormElementInterface>
- Contains all elements of the form, indexed by identifier.
- $finishers : array<int, FinisherInterface>
- The finishers for this form
- $finishersDefinition : array<string, array<string, mixed>>
- $identifier : string
- The identifier of this renderable
- $index : int
- The position of this renderable inside the parent renderable.
- $label : string
- The label of this renderable
- $parentRenderable : CompositeRenderableInterface|null
- The parent renderable
- $persistenceIdentifier : string
- The persistence identifier of the form
- $processingRules : array<string, ProcessingRule>
- Property Mapping Rules, indexed by element identifier
- $renderables : array<int, Page>
- The Form's pages
- $rendererClassName : string
- Renderer class name to be used.
- $renderingOptions : array<string|int, mixed>
- associative array of rendering options
- $templateName : string
- The name of the template file of the renderable.
- $type : string
- Abstract "type" of this Renderable. Is used during the rendering process to determine the template file or the View PHP class being used to render the particular element.
- $typeDefinitions : array<string, array<string, mixed>>
- $validatorResolver : ValidatorResolver|null
- $validatorsDefinition : array<string, array<string, mixed>>
- $variants : array<string|int, mixed>
- associative array of rendering variants
Methods
- __construct() : mixed
- Constructor. Creates a new FormDefinition with the given identifier.
- addElementDefaultValue() : mixed
- Sets the default value of a form element
- addFinisher() : mixed
- Adds the specified finisher to this form
- addPage() : mixed
- Add a new page at the end of the form.
- addValidator() : mixed
- Add a validator to the element.
- addVariant() : mixed
- Adds the specified variant to this form element
- applyVariant() : mixed
- Apply the specified variant to this form element regardless of their conditions
- bind() : FormRuntime
- Bind the current request & response to this form instance, effectively creating a new "instance" of the Form.
- createFinisher() : FinisherInterface
- createPage() : Page
- Create a page with the given $identifier and attach this page to the form.
- createValidator() : ValidatorInterface
- Create a validator for the element.
- createVariant() : RenderableVariantInterface
- getElementByIdentifier() : FormElementInterface|null
- Get a Form Element by its identifier
- getElementDefaultValueByIdentifier() : mixed
- returns the default value of the specified form element or NULL if no default value was set
- getElements() : array<string, FormElementInterface>
- Get all form elements with their identifiers as keys
- getFinishers() : array<int, FinisherInterface>
- Gets all finishers of this form
- getIdentifier() : string
- Get the identifier of the element
- getIndex() : int
- Get the index of the renderable
- getLabel() : string
- Get the label of the renderable
- getPageByIndex() : Page
- Get the page with the passed index. The first page has index zero.
- getPages() : array<int, Page>
- Get the Form's pages
- getParentRenderable() : CompositeRenderableInterface|null
- Get the parent renderable
- getPersistenceIdentifier() : string
- Get the persistence identifier of the form
- getProcessingRule() : ProcessingRule
- getProcessingRules() : array<string, ProcessingRule>
- Get all mapping rules
- getRenderablesRecursively() : array<string|int, RenderableInterface>
- Returns all RenderableInterface instances of this composite renderable recursively
- getRendererClassName() : string
- Get the classname of the renderer
- getRenderingOptions() : array<string|int, mixed>
- Get all rendering options
- getRootForm() : FormDefinition
- Get the root form this element belongs to
- getTemplateName() : string
- Get the templateName name of the renderable
- getType() : string
- Get the type of the renderable
- getTypeDefinitions() : array<string, array<string, mixed>>
- getValidators() : SplObjectStorage
- Get all validators on the element
- getValidatorsDefinition() : array<string, array<string, mixed>>
- getVariants() : array<string|int, RenderableVariantInterface>
- Get all rendering variants
- hasPageWithIndex() : bool
- Check whether a page with the given $index exists
- isEnabled() : bool
- Returns whether this renderable is enabled
- movePageAfter() : mixed
- Move $pageToMove after $referencePage
- movePageBefore() : mixed
- Move $pageToMove before $referencePage
- onRemoveFromParentRenderable() : mixed
- This function is called after a renderable has been removed from its parent renderable.
- registerInFormIfPossible() : mixed
- Register this element at the parent form, if there is a connection to the parent form.
- registerRenderable() : mixed
- Add an element to the ElementsByIdentifier Cache.
- removePage() : mixed
- Remove $pageToRemove from form
- setDataType() : mixed
- Set the datatype
- setIdentifier() : mixed
- Set the identifier of the element
- setIndex() : mixed
- Set the index of the renderable
- setLabel() : mixed
- Set the label which shall be displayed next to the form element
- setOptions() : mixed
- Set multiple properties of this object at once.
- setParentRenderable() : mixed
- Set the parent renderable
- setRendererClassName() : mixed
- Set the renderer class name
- setRenderingOption() : mixed
- Set the rendering option $key to $value.
- unregisterRenderable() : mixed
- Remove an element from the ElementsByIdentifier cache
- addRenderable() : mixed
- Add a renderable to the list of child renderables.
- initializeFromFormDefaults() : mixed
- Initialize the form defaults of the current type
- moveRenderableAfter() : mixed
- Move $renderableToMove after $referenceRenderable
- moveRenderableBefore() : mixed
- Move $renderableToMove before $referenceRenderable
- removeRenderable() : mixed
- Remove a renderable from this renderable.
Properties
$elementDefaultValues
Form element default values in the format ['elementIdentifier' => 'default value']
protected
array<string, mixed>
$elementDefaultValues
= []
$elementsByIdentifier
Contains all elements of the form, indexed by identifier.
protected
array<string, FormElementInterface>
$elementsByIdentifier
= []
Is used as internal cache as we need this really often.
$finishers
The finishers for this form
protected
array<int, FinisherInterface>
$finishers
= []
$finishersDefinition
protected
array<string, array<string, mixed>>
$finishersDefinition
$identifier
The identifier of this renderable
protected
string
$identifier
$index
The position of this renderable inside the parent renderable.
protected
int
$index
= 0
$label
The label of this renderable
protected
string
$label
= ''
$parentRenderable
The parent renderable
protected
CompositeRenderableInterface|null
$parentRenderable
$persistenceIdentifier
The persistence identifier of the form
protected
string
$persistenceIdentifier
$processingRules
Property Mapping Rules, indexed by element identifier
protected
array<string, ProcessingRule>
$processingRules
= []
$renderables
The Form's pages
protected
array<int, Page>
$renderables
= []
$rendererClassName
Renderer class name to be used.
protected
string
$rendererClassName
= ''
$renderingOptions
associative array of rendering options
protected
array<string|int, mixed>
$renderingOptions
= []
$templateName
The name of the template file of the renderable.
protected
string
$templateName
= ''
$type
Abstract "type" of this Renderable. Is used during the rendering process to determine the template file or the View PHP class being used to render the particular element.
protected
string
$type
$typeDefinitions
protected
array<string, array<string, mixed>>
$typeDefinitions
$validatorResolver
protected
ValidatorResolver|null
$validatorResolver
= null
$validatorsDefinition
protected
array<string, array<string, mixed>>
$validatorsDefinition
$variants
associative array of rendering variants
protected
array<string|int, mixed>
$variants
= []
Methods
__construct()
Constructor. Creates a new FormDefinition with the given identifier.
public
__construct(string $identifier[, array<string|int, mixed> $prototypeConfiguration = [] ][, string $type = 'Form' ][, string|null $persistenceIdentifier = null ]) : mixed
Parameters
- $identifier : string
-
The Form Definition's identifier, must be a non-empty string.
- $prototypeConfiguration : array<string|int, mixed> = []
-
overrides form defaults of this definition
- $type : string = 'Form'
-
element type of this form
- $persistenceIdentifier : string|null = null
-
the persistence identifier of the form
Tags
addElementDefaultValue()
Sets the default value of a form element
public
addElementDefaultValue(string $elementIdentifier, mixed $defaultValue) : mixed
Parameters
- $elementIdentifier : string
-
identifier of the form element. This supports property paths!
- $defaultValue : mixed
addFinisher()
Adds the specified finisher to this form
public
addFinisher(FinisherInterface $finisher) : mixed
Parameters
- $finisher : FinisherInterface
addPage()
Add a new page at the end of the form.
public
addPage(Page $page) : mixed
Parameters
- $page : Page
Tags
addValidator()
Add a validator to the element.
public
addValidator(ValidatorInterface $validator) : mixed
Parameters
- $validator : ValidatorInterface
addVariant()
Adds the specified variant to this form element
public
addVariant(RenderableVariantInterface $variant) : mixed
Parameters
- $variant : RenderableVariantInterface
applyVariant()
Apply the specified variant to this form element regardless of their conditions
public
applyVariant(RenderableVariantInterface $variant) : mixed
Parameters
- $variant : RenderableVariantInterface
bind()
Bind the current request & response to this form instance, effectively creating a new "instance" of the Form.
public
bind(RequestInterface $request) : FormRuntime
Parameters
- $request : RequestInterface
Return values
FormRuntimecreateFinisher()
public
createFinisher(string $finisherIdentifier[, array<string|int, mixed> $options = [] ]) : FinisherInterface
Parameters
- $finisherIdentifier : string
-
identifier of the finisher as registered in the current form (for example: "Redirect")
- $options : array<string|int, mixed> = []
-
options for this finisher in the format ['option1' => 'value1', 'option2' => 'value2', ...]
Tags
Return values
FinisherInterfacecreatePage()
Create a page with the given $identifier and attach this page to the form.
public
createPage(string $identifier[, string $typeName = 'Page' ]) : Page
- Create Page object based on the given $typeName
- set defaults inside the Page object
- attach Page object to this form
- return the newly created Page object
Parameters
- $identifier : string
-
Identifier of the new page
- $typeName : string = 'Page'
-
Type of the new page
Tags
Return values
Page —the newly created page
createValidator()
Create a validator for the element.
public
createValidator(string $validatorIdentifier[, array<string|int, mixed> $options = [] ]) : ValidatorInterface
Parameters
- $validatorIdentifier : string
- $options : array<string|int, mixed> = []
Tags
Return values
ValidatorInterfacecreateVariant()
public
createVariant(array<string|int, mixed> $options) : RenderableVariantInterface
Parameters
- $options : array<string|int, mixed>
Return values
RenderableVariantInterfacegetElementByIdentifier()
Get a Form Element by its identifier
public
getElementByIdentifier(string $elementIdentifier) : FormElementInterface|null
If identifier does not exist, returns NULL.
Parameters
- $elementIdentifier : string
Return values
FormElementInterface|null —The element with the given $elementIdentifier or NULL if none found
getElementDefaultValueByIdentifier()
returns the default value of the specified form element or NULL if no default value was set
public
getElementDefaultValueByIdentifier(string $elementIdentifier) : mixed
Parameters
- $elementIdentifier : string
-
identifier of the form element. This supports property paths!
Return values
mixed —The elements default value
getElements()
Get all form elements with their identifiers as keys
public
getElements() : array<string, FormElementInterface>
Return values
array<string, FormElementInterface>getFinishers()
Gets all finishers of this form
public
getFinishers() : array<int, FinisherInterface>
Return values
array<int, FinisherInterface>getIdentifier()
Get the identifier of the element
public
getIdentifier() : string
Return values
stringgetIndex()
Get the index of the renderable
public
getIndex() : int
Return values
intgetLabel()
Get the label of the renderable
public
getLabel() : string
Return values
stringgetPageByIndex()
Get the page with the passed index. The first page has index zero.
public
getPageByIndex(int $index) : Page
If page at $index does not exist, an exception is thrown. @see hasPageWithIndex()
Parameters
- $index : int
Tags
Return values
Page —the page
getPages()
Get the Form's pages
public
getPages() : array<int, Page>
Return values
array<int, Page> —The Form's pages in the correct order
getParentRenderable()
Get the parent renderable
public
getParentRenderable() : CompositeRenderableInterface|null
Return values
CompositeRenderableInterface|nullgetPersistenceIdentifier()
Get the persistence identifier of the form
public
getPersistenceIdentifier() : string
Return values
stringgetProcessingRule()
public
getProcessingRule(string $propertyPath) : ProcessingRule
Parameters
- $propertyPath : string
Return values
ProcessingRulegetProcessingRules()
Get all mapping rules
public
getProcessingRules() : array<string, ProcessingRule>
Return values
array<string, ProcessingRule>getRenderablesRecursively()
Returns all RenderableInterface instances of this composite renderable recursively
public
getRenderablesRecursively() : array<string|int, RenderableInterface>
Return values
array<string|int, RenderableInterface>getRendererClassName()
Get the classname of the renderer
public
getRendererClassName() : string
Return values
string —the renderer class name
getRenderingOptions()
Get all rendering options
public
getRenderingOptions() : array<string|int, mixed>
Return values
array<string|int, mixed> —associative array of rendering options
getRootForm()
Get the root form this element belongs to
public
getRootForm() : FormDefinition
Tags
Return values
FormDefinitiongetTemplateName()
Get the templateName name of the renderable
public
getTemplateName() : string
Return values
stringgetType()
Get the type of the renderable
public
getType() : string
Return values
stringgetTypeDefinitions()
public
getTypeDefinitions() : array<string, array<string, mixed>>
Return values
array<string, array<string, mixed>>getValidators()
Get all validators on the element
public
getValidators() : SplObjectStorage
Return values
SplObjectStoragegetValidatorsDefinition()
public
getValidatorsDefinition() : array<string, array<string, mixed>>
Return values
array<string, array<string, mixed>>getVariants()
Get all rendering variants
public
getVariants() : array<string|int, RenderableVariantInterface>
Return values
array<string|int, RenderableVariantInterface>hasPageWithIndex()
Check whether a page with the given $index exists
public
hasPageWithIndex(int $index) : bool
Parameters
- $index : int
Return values
bool —TRUE if a page with the given $index exists, otherwise FALSE
isEnabled()
Returns whether this renderable is enabled
public
isEnabled() : bool
Return values
boolmovePageAfter()
Move $pageToMove after $referencePage
public
movePageAfter(Page $pageToMove, Page $referencePage) : mixed
Parameters
movePageBefore()
Move $pageToMove before $referencePage
public
movePageBefore(Page $pageToMove, Page $referencePage) : mixed
Parameters
onRemoveFromParentRenderable()
This function is called after a renderable has been removed from its parent renderable.
public
onRemoveFromParentRenderable() : mixed
This just passes the event down to all child renderables of this composite renderable.
registerInFormIfPossible()
Register this element at the parent form, if there is a connection to the parent form.
public
registerInFormIfPossible() : mixed
registerRenderable()
Add an element to the ElementsByIdentifier Cache.
public
registerRenderable(RenderableInterface $renderable) : mixed
Parameters
- $renderable : RenderableInterface
Tags
removePage()
Remove $pageToRemove from form
public
removePage(Page $pageToRemove) : mixed
Parameters
- $pageToRemove : Page
setDataType()
Set the datatype
public
setDataType(string $dataType) : mixed
Parameters
- $dataType : string
setIdentifier()
Set the identifier of the element
public
setIdentifier(string $identifier) : mixed
Parameters
- $identifier : string
setIndex()
Set the index of the renderable
public
setIndex(int $index) : mixed
Parameters
- $index : int
setLabel()
Set the label which shall be displayed next to the form element
public
setLabel(string $label) : mixed
Parameters
- $label : string
setOptions()
Set multiple properties of this object at once.
public
setOptions(array<string|int, mixed> $options[, bool $resetFinishers = false ]) : mixed
Every property which has a corresponding set* method can be set using the passed $options array.
Parameters
- $options : array<string|int, mixed>
- $resetFinishers : bool = false
setParentRenderable()
Set the parent renderable
public
setParentRenderable(CompositeRenderableInterface $parentRenderable) : mixed
Parameters
- $parentRenderable : CompositeRenderableInterface
setRendererClassName()
Set the renderer class name
public
setRendererClassName(string $rendererClassName) : mixed
Parameters
- $rendererClassName : string
setRenderingOption()
Set the rendering option $key to $value.
public
setRenderingOption(string $key, mixed $value) : mixed
Parameters
- $key : string
- $value : mixed
unregisterRenderable()
Remove an element from the ElementsByIdentifier cache
public
unregisterRenderable(RenderableInterface $renderable) : mixed
Parameters
- $renderable : RenderableInterface
addRenderable()
Add a renderable to the list of child renderables.
protected
addRenderable(RenderableInterface $renderable) : mixed
This function will be wrapped by the subclasses, f.e. with an "addPage" or "addElement" method with the correct type hint.
Parameters
- $renderable : RenderableInterface
Tags
initializeFromFormDefaults()
Initialize the form defaults of the current type
protected
initializeFromFormDefaults() : mixed
Tags
moveRenderableAfter()
Move $renderableToMove after $referenceRenderable
protected
moveRenderableAfter(RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable) : mixed
This function will be wrapped by the subclasses, f.e. with an "movePageAfter" or "moveElementAfter" method with the correct type hint.
Parameters
- $renderableToMove : RenderableInterface
- $referenceRenderable : RenderableInterface
Tags
moveRenderableBefore()
Move $renderableToMove before $referenceRenderable
protected
moveRenderableBefore(RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable) : mixed
This function will be wrapped by the subclasses, f.e. with an "movePageBefore" or "moveElementBefore" method with the correct type hint.
Parameters
- $renderableToMove : RenderableInterface
- $referenceRenderable : RenderableInterface
Tags
removeRenderable()
Remove a renderable from this renderable.
protected
removeRenderable(RenderableInterface $renderableToRemove) : mixed
This function will be wrapped by the subclasses, f.e. with an "removePage" or "removeElement" method with the correct type hint.
Parameters
- $renderableToRemove : RenderableInterface