.. include:: /Includes.rst.txt .. _creating-viewhelpers: ==================== Creating ViewHelpers ==================== Creating a ViewHelper is extremely simple. First, make sure you read the :doc:`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_combine` 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:for` 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: .. code-block:: xml
{key}
{item}
To enable this usage we must then create a ViewHelper class: .. code-block:: php 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: .. code-block:: xml {myValuesArray} Naturally this implies that any ViewHelper which returns a string compatible value (including numbers and objects which have a `__toString()` 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_tags`, `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.