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.

Internal

May change any time, use FormFactoryInterface to select a different FormDefinition if needed

Tags
todo:

Declare final in v12

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
$request  : ServerRequestInterface|null
$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
getRequest()  : ServerRequestInterface|null
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.
setRequest()  : void
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.

$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 = ''

$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 = []

$request

protected ServerRequestInterface|null $request = null

$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

$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
throws
IdentifierNotValidException

if the identifier was not valid

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
Internal

addPage()

Add a new page at the end of the form.

public addPage(Page $page) : mixed

Instead of this method, you should often use instead.

Parameters
$page : Page
Tags
throws
FormDefinitionConsistencyException

if Page is already added to a FormDefinition

see
createPage

createFinisher()

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
throws
FinisherPresetNotFoundException
Return values
FinisherInterface

createPage()

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
throws
TypeDefinitionNotFoundException
Return values
Page —

the newly created page

getElementByIdentifier()

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!

Internal
Return values
mixed —

The elements default value

getIdentifier()

Get the identifier of the element

public getIdentifier() : string
Return values
string

getIndex()

Get the index of the renderable

public getIndex() : int
Internal
Return values
int

getLabel()

Get the label of the renderable

public getLabel() : string
Return values
string

getPageByIndex()

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
throws
Exception

if the specified index does not exist

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

getPersistenceIdentifier()

Get the persistence identifier of the form

public getPersistenceIdentifier() : string
Internal
Return values
string

getRenderablesRecursively()

Returns all RenderableInterface instances of this composite renderable recursively

public getRenderablesRecursively() : array<string|int, RenderableInterface>
Internal
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

getRequest()

public getRequest() : ServerRequestInterface|null
Return values
ServerRequestInterface|null

getTemplateName()

Get the templateName name of the renderable

public getTemplateName() : string
Return values
string

getType()

Get the type of the renderable

public getType() : string
Return values
string

getTypeDefinitions()

public getTypeDefinitions() : array<string, array<string, mixed>>
Internal
Return values
array<string, array<string, mixed>>

getValidators()

Get all validators on the element

public getValidators() : SplObjectStorage
Internal
Return values
SplObjectStorage

getValidatorsDefinition()

public getValidatorsDefinition() : array<string, array<string, mixed>>
Internal
Return values
array<string, array<string, mixed>>

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
bool

movePageAfter()

Move $pageToMove after $referencePage

public movePageAfter(Page $pageToMove, Page $referencePage) : mixed
Parameters
$pageToMove : Page
$referencePage : Page

movePageBefore()

Move $pageToMove before $referencePage

public movePageBefore(Page $pageToMove, Page $referencePage) : mixed
Parameters
$pageToMove : Page
$referencePage : Page

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.

Internal

registerInFormIfPossible()

Register this element at the parent form, if there is a connection to the parent form.

public registerInFormIfPossible() : mixed
Internal

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
Internal

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
Internal

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

setRequest()

public setRequest(ServerRequestInterface|null $request) : void
Parameters
$request : ServerRequestInterface|null 

        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results