TYPO3CMS  8
 All Classes Namespaces Files Functions Variables Pages
FormDefinition Class Reference
Inheritance diagram for FormDefinition:
AbstractCompositeRenderable AbstractRenderable CompositeRenderableInterface RenderableInterface RenderableInterface RootRenderableInterface RootRenderableInterface

Public Member Functions

 injectObjectManager (\TYPO3\CMS\Extbase\Object\ObjectManagerInterface $objectManager)
 
 __construct (string $identifier, array $prototypeConfiguration=[], string $type= 'Form', string $persistenceIdentifier=null)
 
 setOptions (array $options)
 
 createPage (string $identifier, string $typeName= 'Page')
 
 addPage (Page $page)
 
 getPages ()
 
 hasPageWithIndex (int $index)
 
 getPageByIndex (int $index)
 
 addFinisher (FinisherInterface $finisher)
 
 createFinisher (string $finisherIdentifier, array $options=[])
 
 getFinishers ()
 
 registerRenderable (RenderableInterface $renderable)
 
 unregisterRenderable (RenderableInterface $renderable)
 
 getElementByIdentifier (string $elementIdentifier)
 
 addElementDefaultValue (string $elementIdentifier, $defaultValue)
 
 getElementDefaultValueByIdentifier (string $elementIdentifier)
 
 movePageBefore (Page $pageToMove, Page $referencePage)
 
 movePageAfter (Page $pageToMove, Page $referencePage)
 
 removePage (Page $pageToRemove)
 
 bind (Request $request, Response $response)
 
 getProcessingRule (string $propertyPath)
 
 getProcessingRules ()
 
 getTypeDefinitions ()
 
 getValidatorsDefinition ()
 
 getPersistenceIdentifier ()
 
- Public Member Functions inherited from AbstractCompositeRenderable
 getRenderablesRecursively ()
 
 registerInFormIfPossible ()
 
 onRemoveFromParentRenderable ()
 
- Public Member Functions inherited from AbstractRenderable
 getType ()
 
 getIdentifier ()
 
 setOptions (array $options)
 
 createValidator (string $validatorIdentifier, array $options=[])
 
 addValidator (ValidatorInterface $validator)
 
 getValidators ()
 
 setDataType (string $dataType)
 
 setRendererClassName (string $rendererClassName)
 
 getRendererClassName ()
 
 getRenderingOptions ()
 
 setRenderingOption (string $key, $value)
 
 getParentRenderable ()
 
 setParentRenderable (CompositeRenderableInterface $parentRenderable)
 
 getRootForm ()
 
 registerInFormIfPossible ()
 
 onRemoveFromParentRenderable ()
 
 getIndex ()
 
 setIndex (int $index)
 
 getLabel ()
 
 setLabel (string $label)
 
 beforeRendering (FormRuntime $formRuntime)
 
 onBuildingFinished ()
 

Protected Member Functions

 initializeFromFormDefaults ()
 
- Protected Member Functions inherited from AbstractCompositeRenderable
 addRenderable (RenderableInterface $renderable)
 
 moveRenderableBefore (RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable)
 
 moveRenderableAfter (RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable)
 
 removeRenderable (RenderableInterface $renderableToRemove)
 

Protected Attributes

 $objectManager
 
 $finishers = []
 
 $processingRules = []
 
 $elementsByIdentifier = []
 
 $elementDefaultValues = []
 
 $typeDefinitions
 
 $validatorsDefinition
 
 $finishersDefinition
 
 $persistenceIdentifier = null
 
- Protected Attributes inherited from AbstractCompositeRenderable
 $renderables = []
 
- Protected Attributes inherited from AbstractRenderable
 $type
 
 $identifier
 
 $parentRenderable
 
 $label = ''
 
 $renderingOptions = []
 
 $rendererClassName = null
 
 $index = 0
 

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 = $this->objectManager->get(FormDefinition::class, 'myForm');

$page1 = $this->objectManager->get(Page::class, 'page1'); $formDefinition->addPage($page);

$element1 = $this->objectManager->get(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 = $this->objectManager->get(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'
    ],
    'Textfield' => [
      'implementationClassName' => 'TYPO3'
    ]
  ]
]

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',
      'label' => 'this is the label of the page if nothing is specified'
    ],
    'Textfield' => [
      'implementationClassName' => 'TYPO3',
      '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 extensions's yaml settings, and the TYPO3\CMS\Form\Domain\Configuration\ConfigurationServicecontainshelpermethodswhichreturntheready-to-use*$prototypeConfiguration*.<h1>PropertyMappingandValidationRules</h1>BesidesPagesandFormElements,theFormDefinitioncancontaininformationaboutthe<em>formatofthedata</em>whichisinputtedintotheform.Thisgenerallymeans:-expectedDataTypes-PropertyMappingConfigurationtobeused-ValidationRuleswhichshouldapply<h2>BackgroundInfo</h2>YoumightwonderwhyDataTypesandValidationRulesare<em>notattachedtoeachFormElementitself</em>.Iftheformshouldcreatea<em>hierarchicaloutputstructure</em>suchasamulti-dimensionalarrayoraPHPobject,yourexpecteddatastructuremightlookasfollows:<pre>-person--firstName--lastName--address---street---city</pre>Now,let'simagineyouwanttoedit<em>person.address.street</em>and<em>person.address.city</em>,butwanttovalidatethatthe<em>combination</em>of<em>street</em>and<em>city</em>isvalidaccordingtosomeaddressdatabase.Inthiscase,theformelementswouldbeconfiguredtofill<em>street</em>and<em>city</em>,butthe<em>validator</em>needstobeattachedtothe<em>compoundobject</em><em>address</em>,asbothpartsneedtobevalidatedtogether.<h1>ConnectingFormElementstotheoutputdatastructure</h1>The<em>identifier</em>ofthe<em>FormElement</em>ismostimportant,asitdetermineswhereintheoutputstructurethevaluewhichisenteredbytheuserisplaced,andthusalsodetermineswhichvalidationrulesneedtoapply.Usingtheaboveexample,ifyouwanttocreateaFormElementforthe<em>street</em>,youshouldusetheidentifier<em>person.address.street</em>.<h1>RenderingaFormDefinition</h1>Inordertotrigger<em>rendering</em>onaFormDefinition,thecurrent@link\TYPO3\CMS\Extbase\Mvc\Web\RequestneedstobeboundtotheFormDefinition,resultingina@link\TYPO3\CMS\Form\Domain\Runtime\FormRuntimeobjectwhichcontainsthe<em>RuntimeState</em>oftheform(suchasthecurrentlyinsertedvalues)./&mdash;codephp<h1>$currentRequestand$currentResponseneedtobeavailable,f.e.insideacontrolleryouwould</h1><h1>use$this->requestand$this->response;insideaViewHelperyouwoulduse$this->controllerContext->getRequest()</h1><h1>and$this->controllerContext->getResponse()</h1>$form=$formDefinition->bind($currentRequest, $currentResponse);<h1>now,youcanusethe$formobjecttogetinformationaboutthecurrently</h1><h1>enteredvaluesintotheform,etc.</h1>---Refertothe@link\TYPO3\CMS\Form\Domain\Runtime\FormRuntimeAPIdocforfurtherinformation.Scope:frontend<strong>ThisclassisNOTmeanttobesubclassedbydevelopers.</strong>

Definition at line 214 of file FormDefinition.php.

Constructor & Destructor Documentation

__construct ( string  $identifier,
array  $prototypeConfiguration = [],
string  $type = 'Form',
string  $persistenceIdentifier = null 
)

Constructor. Creates a new FormDefinition with the given identifier.

Parameters
string$identifierThe Form Definition's identifier, must be a non-empty string.
array$prototypeConfigurationoverrides form defaults of this definition
string$typeelement type of this form
string$persistenceIdentifierthe persistence identifier of the form
Exceptions
IdentifierNotValidExceptionif the identifier was not valid

Definition at line 292 of file FormDefinition.php.

References AbstractRenderable\$identifier, FormDefinition\$persistenceIdentifier, AbstractRenderable\$type, and FormDefinition\initializeFromFormDefaults().

Member Function Documentation

addElementDefaultValue ( string  $elementIdentifier,
  $defaultValue 
)

Sets the default value of a form element

Parameters
string$elementIdentifieridentifier of the form element. This supports property paths!
mixed$defaultValue
Returns
void

Definition at line 576 of file FormDefinition.php.

References ArrayUtility\setValueByPath().

addFinisher ( FinisherInterface  $finisher)

Adds the specified finisher to this form

Parameters
FinisherInterface$finisher
Returns
void

Definition at line 483 of file FormDefinition.php.

Referenced by FormDefinition\createFinisher().

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
Returns
void
Exceptions
FormDefinitionConsistencyExceptionif Page is already added to a FormDefinition
See also
createPage

Definition at line 430 of file FormDefinition.php.

References AbstractCompositeRenderable\addRenderable().

Referenced by FormDefinition\createPage().

bind ( Request  $request,
Response  $response 
)

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

Parameters
Request$request
Response$response
Returns
FormRuntime

Definition at line 646 of file FormDefinition.php.

createFinisher ( string  $finisherIdentifier,
array  $options = [] 
)
Parameters
string$finisherIdentifieridentifier of the finisher as registered in the current form (for example: "Redirect")
array$optionsoptions for this finisher in the format ['option1' => 'value1', 'option2' => 'value2', ...]
Returns
FinisherInterface
Exceptions
FinisherPresetNotFoundException

Definition at line 495 of file FormDefinition.php.

References FormDefinition\addFinisher(), and ArrayUtility\mergeRecursiveWithOverrule().

Referenced by FormDefinition\setOptions().

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$identifierIdentifier of the new page
string$typeNameType of the new page
Returns
Page the newly created page
Exceptions
TypeDefinitionNotFoundException

Definition at line 382 of file FormDefinition.php.

References FormDefinition\addPage(), and ArrayUtility\assertAllArrayKeysAreValid().

getElementByIdentifier ( string  $elementIdentifier)

Get a Form Element by its identifier

If identifier does not exist, returns NULL.

Parameters
string$elementIdentifier
Returns
FormElementInterface The element with the given $elementIdentifier or NULL if none found

Definition at line 563 of file FormDefinition.php.

getElementDefaultValueByIdentifier ( string  $elementIdentifier)

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

Parameters
string$elementIdentifieridentifier of the form element. This supports property paths!
Returns
mixed The elements default value

Definition at line 594 of file FormDefinition.php.

References ObjectAccess\getPropertyPath().

getFinishers ( )

Gets all finishers of this form

Returns
[]

Definition at line 517 of file FormDefinition.php.

References FormDefinition\$finishers.

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, or NULL if none found.
Exceptions
FormExceptionif the specified index does not exist

Definition at line 468 of file FormDefinition.php.

References AbstractRenderable\$index, and FormDefinition\hasPageWithIndex().

getPages ( )

Get the Form's pages

Returns
array<Page> The Form's pages in the correct order

Definition at line 441 of file FormDefinition.php.

References AbstractCompositeRenderable\$renderables.

getPersistenceIdentifier ( )

Get the persistence identifier of the form

Returns
string

Definition at line 699 of file FormDefinition.php.

References FormDefinition\$persistenceIdentifier.

getProcessingRule ( string  $propertyPath)
Parameters
string$propertyPath
Returns
ProcessingRule

Definition at line 656 of file FormDefinition.php.

getProcessingRules ( )

Get all mapping rules

Returns
[]

Definition at line 670 of file FormDefinition.php.

References FormDefinition\$processingRules.

getTypeDefinitions ( )
Returns
array

Definition at line 679 of file FormDefinition.php.

References FormDefinition\$typeDefinitions.

getValidatorsDefinition ( )
Returns
array

Definition at line 688 of file FormDefinition.php.

References FormDefinition\$validatorsDefinition.

hasPageWithIndex ( int  $index)

Check whether a page with the given $index exists

Parameters
int$index
Returns
bool TRUE if a page with the given $index exists, otherwise FALSE

Definition at line 453 of file FormDefinition.php.

Referenced by FormDefinition\getPageByIndex().

initializeFromFormDefaults ( )
protected

Initialize the form defaults of the current type

Returns
void
Exceptions
TypeDefinitionNotFoundException

Definition at line 322 of file FormDefinition.php.

References AbstractRenderable\$type, and FormDefinition\setOptions().

Referenced by FormDefinition\__construct().

injectObjectManager ( \TYPO3\CMS\Extbase\Object\ObjectManagerInterface  $objectManager)
Parameters
\TYPO3\CMS\Extbase\Object\ObjectManagerInterface$objectManager

Definition at line 277 of file FormDefinition.php.

References FormDefinition\$objectManager.

movePageAfter ( Page  $pageToMove,
Page  $referencePage 
)

Move $pageToMove after $referencePage

Parameters
Page$pageToMove
Page$referencePage
Returns
void

Definition at line 620 of file FormDefinition.php.

References AbstractCompositeRenderable\moveRenderableAfter().

movePageBefore ( Page  $pageToMove,
Page  $referencePage 
)

Move $pageToMove before $referencePage

Parameters
Page$pageToMove
Page$referencePage
Returns
void

Definition at line 607 of file FormDefinition.php.

References AbstractCompositeRenderable\moveRenderableBefore().

registerRenderable ( RenderableInterface  $renderable)

Add an element to the ElementsByIdentifier Cache.

Parameters
RenderableInterface$renderable
Returns
void
Exceptions
DuplicateFormElementException

Definition at line 530 of file FormDefinition.php.

References RootRenderableInterface\getIdentifier().

removePage ( Page  $pageToRemove)

Remove $pageToRemove from form

Parameters
Page$pageToRemove
Returns
void

Definition at line 632 of file FormDefinition.php.

References AbstractCompositeRenderable\removeRenderable().

setOptions ( array  $options)

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

Parameters
array$options
Returns
void

Definition at line 340 of file FormDefinition.php.

References ArrayUtility\assertAllArrayKeysAreValid(), FormDefinition\createFinisher(), AbstractRenderable\getRenderingOptions(), ArrayUtility\mergeRecursiveWithOverrule(), AbstractRenderable\setRendererClassName(), and AbstractRenderable\setRenderingOption().

Referenced by FormDefinition\initializeFromFormDefaults().

unregisterRenderable ( RenderableInterface  $renderable)

Remove an element from the ElementsByIdentifier cache

Parameters
RenderableInterface$renderable
Returns
void

Definition at line 547 of file FormDefinition.php.

References RootRenderableInterface\getIdentifier().

Member Data Documentation

$elementDefaultValues = []
protected

Definition at line 249 of file FormDefinition.php.

$elementsByIdentifier = []
protected

Definition at line 242 of file FormDefinition.php.

$finishers = []
protected

Definition at line 227 of file FormDefinition.php.

Referenced by FormDefinition\getFinishers().

$finishersDefinition
protected

Definition at line 264 of file FormDefinition.php.

$objectManager
protected

Definition at line 220 of file FormDefinition.php.

Referenced by FormDefinition\injectObjectManager().

$persistenceIdentifier = null
protected
$processingRules = []
protected

Definition at line 234 of file FormDefinition.php.

Referenced by FormDefinition\getProcessingRules().

$typeDefinitions
protected

Definition at line 254 of file FormDefinition.php.

Referenced by FormDefinition\getTypeDefinitions().

$validatorsDefinition
protected

Definition at line 259 of file FormDefinition.php.

Referenced by FormDefinition\getValidatorsDefinition().