Creating ViewHelpers
Creating a ViewHelper is extremely simple. First, make sure you read the chapter about using ViewHelpers so you know where ViewHelper class files are expected to be placed in your own package and that you understand how/why you would require a custom ViewHelper.
Let's create an example ViewHelper which will accept exactly two arguments, both
arrays, and use those arrays to create a new array using array_
which
takes one argument with keys and another of the same size with values. We would
like this new ViewHelper to be usable in inline syntax - for example as value of
the each
argument on f:
to iterate the combined array. And finally, we
would like to be able to specify the "values" array also in the special inline
syntax for tag content:
<html xmlns:mypkg="Vendor\Package\ViewHelpers">
<dl>
<f:for each="{myValuesArray -> mypkg:combine(keys: myKeysArray)}" as="item" key="key">
<dt>{key}</dt>
<dd>{item}</dd>
</f:for>
<dl>
</html>
To enable this usage we must then create a ViewHelper class:
<?php
namespace Vendor\Package\ViewHelpers;
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
/**
* This ViewHelper takes two arrays and returns
* the `array_combine`d result.
*/
class CombineViewHelper extends AbstractViewHelper {
/**
* @return void
*/
public function initializeArguments() {
$this->registerArgument('values', 'array', 'Values to use in array_combine');
$this->registerArgument('keys', 'array', 'Keys to use in array_combine', true);
}
/**
* Combines two arrays using one for keys and
* the other for values. If values are not provided
* in argument it can be provided as tag content.
*
* @return array
*/
public function render() {
$values = $this->arguments['values'];
$keys = $this->arguments['keys'];
if ($values === null) {
$values = $this->renderChildren();
}
return array_combine($keys, $values);
}
}
And that's all this class requires to work in the described way.
Note that in this example the ViewHelper's render
method returns an array
which means you can't use it in tag mode:
<html xmlns:mypkg="Vendor\Package\ViewHelpers">
<!-- BAD USAGE. Will output string value "Array" -->
<mypkg:combine keys="{myKeysArray}">{myValuesArray}</mypkg:combine>
</html>
Naturally this implies that any ViewHelper which returns a string compatible
value (including numbers and objects which have a __
method) can be
used in tag mode or inline mode - whereas ViewHelpers that return other data
types normally only make sense to use in inline mode; as values of other
ViewHelpers' attributes that require the returned value type. For example,
ViewHelpers which format output should always return a string (examples of such
ViewHelpers might be ones that implement strip_
, nl2br
or other
string-manipulating PHP functions). And data ViewHelpers may return any type,
but must be used a bit more carefully.
In other words: be careful what data types your ViewHelper returns. Non-string-compatible values may cause problems if you use the ViewHelper in ways that were not intended. Like in PHP, data types must either match or be mutually compatible.