TYPO3\CMS\Form\Domain\Model\FormDefinition Class Reference

Inheritance diagram for TYPO3\CMS\Form\Domain\Model\FormDefinition:

Public Member Functions
	setOptions (array $options, bool $resetFinishers=false)
Page	createPage (string $identifier, string $typeName='Page')
	addPage (Page $page)
bool	hasPageWithIndex (int $index)
Page	getPageByIndex (int $index)
	addFinisher (FinisherInterface $finisher)
	createFinisher (string $finisherIdentifier, array $options=[])
list< FinisherInterface >	getFinishers ()
	registerRenderable (RenderableInterface $renderable)
	unregisterRenderable (RenderableInterface $renderable)
FormElementInterface null	getElementByIdentifier (string $elementIdentifier)
	addElementDefaultValue (string $elementIdentifier, $defaultValue)
mixed	getElementDefaultValueByIdentifier (string $elementIdentifier)
	movePageBefore (Page $pageToMove, Page $referencePage)
	movePageAfter (Page $pageToMove, Page $referencePage)
	removePage (Page $pageToRemove)
	bind (RequestInterface $request)
	getProcessingRule (string $propertyPath)
	getPersistenceIdentifier ()
	setRendererClassName (string $rendererClassName)
	getRendererClassName ()
‪Public Member Functions inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable
RenderableInterface[]	getRenderablesRecursively ()
	registerInFormIfPossible ()
	onRemoveFromParentRenderable ()
‪Public Member Functions inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable
	getType ()
	getIdentifier ()
	setIdentifier (string $identifier)
	createValidator (string $validatorIdentifier, array $options=[])
	addValidator (ValidatorInterface $validator)
	getValidators ()
	setDataType (string $dataType)
	getRenderingOptions ()
mixed	setRenderingOption (string $key, $value)
CompositeRenderableInterface null	getParentRenderable ()
	setParentRenderable (CompositeRenderableInterface $parentRenderable)
	getRootForm ()
	getIndex ()
	setIndex (int $index)
	getLabel ()
	setLabel (string $label)
	getTemplateName ()
	isEnabled ()
RenderableVariantInterface[]	getVariants ()
	createVariant (array $options)
	addVariant (RenderableVariantInterface $variant)
	applyVariant (RenderableVariantInterface $variant)

Public Attributes
array< int, function getPages():array { return $this->	renderables
array< string, function getElements():array { return $this->	elementsByIdentifier
array< string, function getProcessingRules():array { return $this->	processingRules
array< string, function getTypeDefinitions():array { return $this->	typeDefinitions
array< string, function getValidatorsDefinition():array { return $this->	validatorsDefinition

Protected Member Functions
array< int, $renderables=array();protected list< FinisherInterface > $finishers=array();protected array< string, $processingRules=array();protected array< string, $elementsByIdentifier=array();protected array< string, $elementDefaultValues=array();protected string $rendererClassName='';protected array< string, $typeDefinitions;protected array< string, $validatorsDefinition;protected array< string, $finishersDefinition;protected string $persistenceIdentifier;public __construct(string $identifier, array $prototypeConfiguration=[], string $type='Form', string $persistenceIdentifier=null) { $this->typeDefinitions=$prototypeConfiguration[ 'formElementsDefinition'] ??[];$this->validatorsDefinition=$prototypeConfiguration[ 'validatorsDefinition'] ??[];$this->finishersDefinition=$prototypeConfiguration[ 'finishersDefinition'] ??[];if(!is_string( $identifier)||strlen( $identifier)===0) { throw new IdentifierNotValidException( 'The given identifier was not a string or the string was empty.', 1477082503);} $this->identifier=$identifier;$this->type=$type;$this->persistenceIdentifier=(string) $persistenceIdentifier;if( $prototypeConfiguration !==[]) { $this->	initializeFromFormDefaults ()
	initializeFromFormDefaults ()
‪Protected Member Functions inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable
	addRenderable (RenderableInterface $renderable)
	moveRenderableBefore (RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable)
	moveRenderableAfter (RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable)
	removeRenderable (RenderableInterface $renderableToRemove)

Additional Inherited Members
‪Protected Attributes inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable
TYPO3 CMS Form Domain Model Renderable RenderableInterface[]	$renderables = array( )
‪Protected Attributes inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable
string	$type
string	$identifier
CompositeRenderableInterface null	$parentRenderable
string	$label = ''
array	$renderingOptions = array( )
int	$index = 0
string	$templateName = ''
array	$variants = array( )
ValidatorResolver	$validatorResolver = null

Detailed Description

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 (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 (FormElementInterface, AbstractFormElement), 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 FormDefinition::addPage or Page::addElement methods and create the Page and FormElement objects manually, it is often better to use the corresponding create* methods (FormDefinition::createPage and Page::createElement), 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'
      ]
    ]
  ]
]

U

sing 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 \TYPO3\CMS\Form\Domain\Configuration\ConfigurationService 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 \TYPO3\CMS\Extbase\Mvc\Request needs to be bound to the FormDefinition,
resulting in a \TYPO3\CMS\Form\Domain\Runtime\FormRuntime 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 \TYPO3\CMS\Form\Domain\Runtime\FormRuntime 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
 
Todo:
‪: Declare final in v12
 

Definition at line 223 of file FormDefinition.php.

Member Function Documentation

addElementDefaultValue()

TYPO3\CMS\Form\Domain\Model\FormDefinition::addElementDefaultValue	(	string	$elementIdentifier,
			$defaultValue
	)

Sets the default value of a form element

Parameters

string	$elementIdentifier	‪identifier of the form element. This supports property paths!
mixed	$defaultValue

Definition at line 570 of file FormDefinition.php.

References TYPO3\CMS\Core\Utility\ArrayUtility\setValueByPath().

addFinisher()

TYPO3\CMS\Form\Domain\Model\FormDefinition::addFinisher

(

FinisherInterface

$finisher

)

Adds the specified finisher to this form

Definition at line 476 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\createFinisher().

addPage()

TYPO3\CMS\Form\Domain\Model\FormDefinition::addPage

(

Page

$page

)

Add a new page at the end of the form.

Instead of this method, you should often use createPage instead.

Parameters

Page

$page

Exceptions

FormDefinitionConsistencyException

‪if Page is already added to a FormDefinition

See also

‪createPage

Definition at line 431 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\addRenderable().

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\createPage().

bind()

TYPO3\CMS\Form\Domain\Model\FormDefinition::bind

(

RequestInterface

$request

)

Bind the current request & response to this form instance, effectively creating a new "instance" of the Form.

Definition at line 621 of file FormDefinition.php.

createFinisher()

TYPO3\CMS\Form\Domain\Model\FormDefinition::createFinisher	(	string	$finisherIdentifier,
		array	$options = []
	)

Parameters

string	$finisherIdentifier	‪identifier of the finisher as registered in the current form (for example: "Redirect")
array	$options	‪options for this finisher in the format ['option1' => 'value1', 'option2' => 'value2', ...]

Exceptions

FinisherPresetNotFoundException

Definition at line 486 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\addFinisher().

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\setOptions().

createPage()

Page TYPO3\CMS\Form\Domain\Model\FormDefinition::createPage	(	string	$identifier,
		string	$typeName = 'Page'
	)

Create a page with the given $identifier and attach this page to the form.

• ‪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

string	$identifier	‪Identifier of the new page
string	$typeName	‪Type of the new page

Returns

‪Page the newly created page

Exceptions

TypeDefinitionNotFoundException

Definition at line 381 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\$identifier, TYPO3\CMS\Form\Domain\Model\FormDefinition\addPage(), TYPO3\CMS\Core\Utility\ArrayUtility\assertAllArrayKeysAreValid(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\typeDefinitions.

getElementByIdentifier()

FormElementInterface null TYPO3\CMS\Form\Domain\Model\FormDefinition::getElementByIdentifier

(

string

$elementIdentifier

)

Get a Form Element by its identifier

If identifier does not exist, returns NULL.

Parameters

string

$elementIdentifier

Returns

‪FormElementInterface|null The element with the given $elementIdentifier or NULL if none found

Definition at line 558 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\elementsByIdentifier.

getElementDefaultValueByIdentifier()

mixed TYPO3\CMS\Form\Domain\Model\FormDefinition::getElementDefaultValueByIdentifier

(

string

$elementIdentifier

)

returns the default value of the specified form element or NULL if no default value was set

Parameters

string

$elementIdentifier

‪identifier of the form element. This supports property paths!

Returns

‪mixed The elements default value

Definition at line 588 of file FormDefinition.php.

References TYPO3\CMS\Extbase\Reflection\ObjectAccess\getPropertyPath().

getFinishers()

list<FinisherInterface> TYPO3\CMS\Form\Domain\Model\FormDefinition::getFinishers

(

)

Gets all finishers of this form

Returns

‪list<FinisherInterface>

Definition at line 507 of file FormDefinition.php.

getPageByIndex()

Page TYPO3\CMS\Form\Domain\Model\FormDefinition::getPageByIndex

(

int

$index

)

Get the page with the passed index. The first page has index zero.

If page at $index does not exist, an exception is thrown.

See also

‪hasPageWithIndex()

Parameters

int

$index

Returns

‪Page the page

Exceptions

FormException

‪if the specified index does not exist

Definition at line 465 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\$index, TYPO3\CMS\Form\Domain\Model\FormDefinition\hasPageWithIndex(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\renderables.

getPersistenceIdentifier()

TYPO3\CMS\Form\Domain\Model\FormDefinition::getPersistenceIdentifier

(

)

Get the persistence identifier of the form

Definition at line 672 of file FormDefinition.php.

getProcessingRule()

TYPO3\CMS\Form\Domain\Model\FormDefinition::getProcessingRule

(

string

$propertyPath

)

Definition at line 630 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\processingRules.

getRendererClassName()

TYPO3\CMS\Form\Domain\Model\FormDefinition::getRendererClassName

(

)

Get the classname of the renderer

Reimplemented from TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable.

Definition at line 688 of file FormDefinition.php.

hasPageWithIndex()

bool TYPO3\CMS\Form\Domain\Model\FormDefinition::hasPageWithIndex

(

int

$index

)

Check whether a page with the given $index exists

Returns

‪bool TRUE if a page with the given $index exists, otherwise FALSE

Definition at line 451 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\renderables.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getPageByIndex().

initializeFromFormDefaults() [1/2]

array<int, $renderables = array( ); protected list<FinisherInterface> $finishers = array( ); protected array<string, $processingRules = array( ); protected array<string, $elementsByIdentifier = array( ); protected array<string, $elementDefaultValues = array( ); protected string $rendererClassName = ''; protected array<string, $typeDefinitions; protected array<string, $validatorsDefinition; protected array<string, $finishersDefinition; protected string $persistenceIdentifier; public __construct( string $identifier, array $prototypeConfiguration = [], string $type = 'Form', string $persistenceIdentifier = null ) { $this->typeDefinitions = $prototypeConfiguration['formElementsDefinition'] ?? []; $this->validatorsDefinition = $prototypeConfiguration['validatorsDefinition'] ?? []; $this->finishersDefinition = $prototypeConfiguration['finishersDefinition'] ?? []; if (!is_string($identifier) || strlen($identifier) === 0) { throw new IdentifierNotValidException('The given identifier was not a string or the string was empty.', 1477082503); } $this->identifier = $identifier; $this->type = $type; $this->persistenceIdentifier = (string)$persistenceIdentifier; if ($prototypeConfiguration !== []) { $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::initializeFromFormDefaults ( )

protected

The Form's pages

Page>

initializeFromFormDefaults() [2/2]

TYPO3\CMS\Form\Domain\Model\FormDefinition::initializeFromFormDefaults ( )

protected

Initialize the form defaults of the current type

Exceptions

TypeDefinitionNotFoundException

Definition at line 318 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\$type, TYPO3\CMS\Form\Domain\Model\FormDefinition\setOptions(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\typeDefinitions.

movePageAfter()

TYPO3\CMS\Form\Domain\Model\FormDefinition::movePageAfter	(	Page	$pageToMove,
		Page	$referencePage
	)

Move $pageToMove after $referencePage

Definition at line 604 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\moveRenderableAfter().

movePageBefore()

TYPO3\CMS\Form\Domain\Model\FormDefinition::movePageBefore	(	Page	$pageToMove,
		Page	$referencePage
	)

Move $pageToMove before $referencePage

Definition at line 596 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\moveRenderableBefore().

registerRenderable()

TYPO3\CMS\Form\Domain\Model\FormDefinition::registerRenderable

(

RenderableInterface

$renderable

)

Add an element to the ElementsByIdentifier Cache.

Exceptions

DuplicateFormElementException

Definition at line 518 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\elementsByIdentifier, and TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface\getIdentifier().

removePage()

TYPO3\CMS\Form\Domain\Model\FormDefinition::removePage

(

Page

$pageToRemove

)

Remove $pageToRemove from form

Definition at line 612 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\removeRenderable().

setOptions()

TYPO3\CMS\Form\Domain\Model\FormDefinition::setOptions	(	array	$options,
		bool	$resetFinishers = false
	)

Set multiple properties of this object at once. Every property which has a corresponding set* method can be set using the passed $options array.

Implements TYPO3\CMS\Form\Domain\Model\Renderable\VariableRenderableInterface.

Definition at line 334 of file FormDefinition.php.

References TYPO3\CMS\Core\Utility\ArrayUtility\assertAllArrayKeysAreValid(), TYPO3\CMS\Form\Domain\Model\FormDefinition\createFinisher(), TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\createVariant(), TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\setLabel(), TYPO3\CMS\Form\Domain\Model\FormDefinition\setRendererClassName(), and TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\setRenderingOption().

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\initializeFromFormDefaults().

setRendererClassName()

TYPO3\CMS\Form\Domain\Model\FormDefinition::setRendererClassName

(

string

$rendererClassName

)

Set the renderer class name

Definition at line 680 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\setOptions().

unregisterRenderable()

TYPO3\CMS\Form\Domain\Model\FormDefinition::unregisterRenderable

(

RenderableInterface

$renderable

)

Remove an element from the ElementsByIdentifier cache

Definition at line 533 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\elementsByIdentifier, and TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface\getIdentifier().

Member Data Documentation

elementsByIdentifier

array<string, function getElements(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::elementsByIdentifier

Get all form elements with their identifiers as keys

Returns

‪array<string, FormElementInterface>

Definition at line 547 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getElementByIdentifier(), TYPO3\CMS\Form\Domain\Model\FormDefinition\registerRenderable(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\unregisterRenderable().

processingRules

array<string, function getProcessingRules(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::processingRules

Get all mapping rules

Returns

‪array<string, ProcessingRule>

Definition at line 646 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getProcessingRule().

renderables

array<int, function getPages(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::renderables

Get the Form's pages

Returns

‪array<int, Page> The Form's pages in the correct order

Definition at line 443 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getPageByIndex(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\hasPageWithIndex().

typeDefinitions

array<string, function getTypeDefinitions(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::typeDefinitions

Returns

‪array<string, array<string, mixed>>

Definition at line 655 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\createPage(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\initializeFromFormDefaults().

validatorsDefinition

array<string, function getValidatorsDefinition(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::validatorsDefinition

Returns

‪array<string, array<string, mixed>>

Definition at line 664 of file FormDefinition.php.