Extending Form API¶
After working through this guide, you will have learned:
- how to create custom PHP based Form Element implementations
- how to create a custom Form Element renderer
Generally, this guide answers the question: How can the form output be modified with programming?
Custom PHP-based Form Elements¶
In the previous guides you have learned how to create custom Form Elements without writing a single line of PHP. While this is sufficient for most cases where you mainly want to change the visual representation or create a specialized version of an already existing element, there are situations where you want to adjust the Server-side behavior of an element. This is where you want to get your hands dirty and create custom Form Element implementations. Examples for such custom Form Elements are:
- A DatePicker that converts the input to a
DateTime
object - A File upload that validates and converts an uploaded file to a
PersistentResource
- A Captcha image
A Form Element must implement the FormElementInterface
interface located in
Neos.Form/Classes/Core/Model/FormElementInterface.php
.
Tip
Usually you want to extend the provided AbstractFormElement
which already implements
most of the methods of the interface.
Most commonly you create custom Form elements in order to preconfigure the so called Processing Rule
which defines validation and property mapping instructions for an element.
Lets have a look at the DatePicker
Form Element located in Neos.Form/Classes/FormElements/DatePicker.php
:
class DatePicker extends \Neos\Form\Core\Model\AbstractFormElement {
public function initializeFormElement() {
$this->setDataType('DateTime');
}
}
The method initializeFormElement()
is called whenever a Form Element is added to a form.
In this example, we only set the target data type to a DateTime object. This way, property
mapping and type conversion using the registered TypeConverters is automatically triggered.
Besides being able to modify the Form Element configuration during initialization you can also
implement the callbacks beforeRendering()
or/and onSubmit()
in order to adjust the behavior
or representation of the element at runtime.
Lets create a new Form Element that is required only if another form field has been specified (for
example a “subscribe to newsletter” checkbox that requires you to provide an email address if checked).
For this create a new PHP class at Your.Package/Classes/FormElements/ConditionalRequired.php
:
namespace Your\Package\FormElements;
class ConditionalRequired extends \Neos\Form\Core\Model\AbstractFormElement {
/**
* Executed before the current element is outputted to the client
*
* @param \Neos\Form\Core\Runtime\FormRuntime $formRuntime
* @return void
*/
public function beforeRendering(\Neos\Form\Core\Runtime\FormRuntime $formRuntime) {
$this->requireIfTriggerIsSet($formRuntime->getFormState());
}
/**
* Executed after the page containing the current element has been submitted
*
* @param \Neos\Form\Core\Runtime\FormRuntime $formRuntime
* @param mixed $elementValue raw value of the submitted element
* @return void
*/
public function onSubmit(\Neos\Form\Core\Runtime\FormRuntime $formRuntime, &$elementValue) {
$this->requireIfTriggerIsSet($formRuntime->getFormState());
}
/**
* Adds a NotEmptyValidator to the current element if the "trigger" value is not empty.
* The trigger can be configured with $this->properties['triggerPropertyPath']
*
* @param \Neos\Form\Core\Runtime\FormState $formState
* @return void
*/
protected function requireIfTriggerIsSet(\Neos\Form\Core\Runtime\FormState $formState) {
if (!isset($this->properties['triggerPropertyPath'])) {
return;
}
$triggerValue = $formState->getFormValue($this->properties['triggerPropertyPath']);
if ($triggerValue === NULL || $triggerValue === '') {
return;
}
$this->addValidator(new \Neos\Flow\Validation\Validator\NotEmptyValidator());
}
}
beforeRendering()
is invoked just before a Form Element is actually outputted to the client.
It receives a reference to the current FormRuntime
making it possible to access previously
submitted values.
onSubmit()
is called whenever the page containing the current Form Element is submitted. to the
server. In addition to the FormRuntime
this callback also gets passed a reference to the raw value
of the submitted element value before property mapping and validation rules were applied.
In order to use the new Form Element type you first have to extend the Form Definition and specify the
implementationClassName
option:
Neos:
Form:
presets:
somePreset:
# ...
formElementTypes:
'Neos.FormExample:ConditionalRequired':
superTypes:
'Neos.Form:FormElement': TRUE
implementationClassName: 'Neos\FormExample\FormElements\ConditionalRequired'
renderingOptions:
templatePathPattern: 'resource://Neos.Form/Private/Form/SingleLineText.html'
This makes the new Form Element Neos.FormExample:ConditionalRequired
available in the preset
somePreset
and you can use it as follows:
$form = new FormDefinition('myForm', $formDefaults);
$page1 = $form->createPage('page1');
$newsletter = $page1->createElement('newsletter', 'Neos.Form:Checkbox');
$newsletter->setLabel('Subscribe for Newsletter');
$email = $page1->createElement('email', 'Neos.FormExample:ConditionalRequired');
$email->setLabel('E-Mail');
$email->setProperty('triggerPropertyPath', 'newsletter');
The line $email->setProperty('triggerPropertyPath', 'newsletter');
makes the email
Form Element
required depending on the value of the newsletter
element.
This example is really simple but it demonstrates how you can profoundly interact with the Form handling at every level.
Custom Form Element Renderers¶
By default a form and all its elements are rendered with the FluidFormRenderer
which is a specialized
version of the Fluid TemplateView
. For each renderable Form Element there exists an corresponding Fluid
template.
The template path can be changed for all or specific Form Elements as well as layout and partial paths, so
the default renderer is flexible enough to cover most scenarios. However if you want to use your own templating
engine or don’t want to render HTML forms at all (think of Flash or CLI based forms) you can implement your
own Renderer and use it either for the complete form or for certain Form Elements.
As a basic example we want to implement a ListRenderer
that simply outputs specified items as unordered
list. A Form Element Renderer must implement the RendererInterface
interface located in
Neos.Form/Classes/Core/Renderer/RendererInterface.php
and usually you want to extend the provided
AbstractRenderer
which already implements most of the methods of the interface:
namespace Your\Package\Renderers;
class ListRenderer extends \Neos\Form\Core\Renderer\AbstractElementRenderer {
/**
* @param \Neos\Form\Core\Model\Renderable\RootRenderableInterface $renderable
* @return string
*/
public function renderRenderable(\Neos\Form\Core\Model\Renderable\RootRenderableInterface $renderable) {
$renderable->beforeRendering($this->formRuntime);
$items = array();
if ($renderable instanceof \Neos\Form\Core\Model\FormElementInterface) {
$elementProperties = $renderable->getProperties();
if (isset($elementProperties['items'])) {
$items = $elementProperties['items'];
}
}
$content = sprintf('<h3>%s</h3>', htmlspecialchars($renderable->getLabel()));
$content .= '<ul>';
foreach ($items as $item) {
$content .= sprintf('<li>%s</li>', htmlspecialchars($item));
}
$content .= '</ul>';
$content = $this->formRuntime->invokeRenderCallbacks($content, $renderable);
return $content;
}
}
Note
Don’t forget to invoke RootRenderableInterface::beforeRendering()
and FormRuntime::invokeRenderCallbacks()
as shown above.
Tip
If you write your own Renderer make sure to sanitize values with htmlspecialchars()
before outputting
them to prevent invalid HTML and XSS vulnerabilities.
Make sure to have a look at the `FusionRenderer Package<https://packagist.org/packages/neos/form-fusionrenderer>`_ that provides Fusion based rendering for arbitrary Form Elements!