88Developing a custom ViewHelper
99==============================
1010
11- .. deprecated :: Fluid v2.15 (TYPO3 v13.3 / TYPO3 12.4)
12- The traits
13- :php: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithRenderStatic ` and
14- :php: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithContentArgumentAndRender `
15- are deprecated. See section :ref: `migration <fluid-custom-viewhelper-migration >`.
16-
1711This chapter demonstrates how to write a custom Fluid ViewHelper in TYPO3.
1812
1913A "Gravatar" ViewHelper is created, which uses an email address as parameter
@@ -167,13 +161,6 @@ harmful chars are escaped.
167161Creating HTML/XML tags with the :php: `AbstractTagBasedViewHelper `
168162=================================================================
169163
170- .. versionchanged :: Fluid Standalone 2.12 / TYPO3 13.2
171- All TagBasedViewHelpers (such as :html: `<f:image />` or :html: `<f:form .* >`) can now receive
172- arbitrary tag attributes which will be appended to the resulting HTML tag. In the past,
173- this was only possible for a small list of tag attributes, like class, id or lang.
174-
175- See also :ref: `AbstractTagBasedViewHelper-registerTagAttribute-migration `.
176-
177164For ViewHelpers which create HTML/XML tags, Fluid provides an enhanced base
178165class: :php: `\T YPO3Fluid\F luid\C ore\V iewHelper\A bstractTagBasedViewHelper `. This
179166base class provides an instance of
@@ -250,35 +237,6 @@ The GravatarViewHelper creates an img tag builder, which has a method named
250237:php: `render() `. After configuring the tag builder instance, the rendered tag
251238markup is returned.
252239
253- .. _AbstractTagBasedViewHelper-registerTagAttribute :
254-
255- :php: `$this->registerTagAttribute() `
256- ------------------------------------
257-
258- .. deprecated :: Fluid standalone 2.12 / TYPO3 v13.2
259- The methods php:`$this->registerTagAttribute() ` and
260- :php: `registerUniversalTagAttributes() ` have been deprecated. They can be
261- removed on dropping TYPO3 v12.4 support.
262-
263- .. _AbstractTagBasedViewHelper-registerTagAttribute-migration :
264-
265- Migration: Remove registerUniversalTagAttributes and registerTagAttribute
266- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
267-
268- .. literalinclude :: _CustomViewHelper/_GravatarViewHelper13.diff
269- :caption: EXT:my_extension/Classes/ViewHelpers/GravatarViewHelper.php
270-
271- When removing the call, attributes registered by the call are now available in
272- :php: `$this->additionalArguments `, and no longer in :php: `$this->arguments `.
273- This *may * need adaption within single ViewHelpers, *if * they handle such
274- attributes on their own.
275-
276- If you need to support both TYPO3 v12.4 and v13, you can leave the calls
277- in until dropping TYPO3 v12.4 support.
278-
279- .. literalinclude :: _CustomViewHelper/_GravatarViewHelper_Initialize.diff
280- :caption: EXT:my_extension/Classes/ViewHelpers/GravatarViewHelper.php
281-
282240.. _insert-optional-arguments :
283241
284242Insert optional arguments with default values
@@ -302,11 +260,6 @@ the `size` attribute becomes optional.
302260Prepare ViewHelper for inline syntax
303261====================================
304262
305- .. deprecated :: Fluid v2.15 (TYPO3 v13.3 / TYPO3 12.4)
306- In former versions this was done by using the now deprecated trait
307- :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithContentArgumentAndRender `.
308- See section :ref: `migration <fluid-custom-viewhelper-migration >`.
309-
310263So far, the Gravatar ViewHelper has focused on the tag structure of the
311264ViewHelper. The call to render the ViewHelper was written with tag syntax, which
312265seemed obvious because it itself returns a tag:
@@ -360,21 +313,11 @@ This returns the evaluated object between the opening and closing tag.
360313Handle additional arguments
361314===========================
362315
363- .. versionchanged :: Fluid Standalone 2.12 / TYPO3 13.2
364- All ViewHelpers implementing
365- :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\A bstractTagBasedViewHelper `
366- can now receive arbitrary tag attributes which will be appended to the
367- resulting HTML tag. In the past, this was only possible for
368- explicitly registered arguments.
369-
370- See also :ref: `AbstractTagBasedViewHelper-registerTagAttribute-migration `.
371-
372- If a ViewHelper allows further arguments which have not been explicitly
373- configured, the :php: `handleAdditionalArguments() ` method can be implemented.
374-
375- ViewHelper implementing
376- :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\A bstractTagBasedViewHelper ` do
377- not need to use this as all arguments are passed on automatically.
316+ All ViewHelpers implementing
317+ :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\A bstractTagBasedViewHelper `
318+ can receive arbitrary tag attributes which will be appended to the
319+ resulting HTML tag. In the past, this was only possible for
320+ explicitly registered arguments.
378321
379322.. _the-different-render-methods :
380323
@@ -404,84 +347,13 @@ Example implementation:
404347.. literalinclude :: _CustomViewHelper/_StrtolowerViewHelper.php
405348 :caption: EXT:my_extension/Classes/ViewHelpers/StrtolowerViewHelper.php
406349
407- .. _renderstatic-method :
408-
409- `renderStatic() ` method
410- -----------------------
411-
412- .. deprecated :: Fluid v2.15 (TYPO3 v13.3 / TYPO3 12.4)
413- The trait
414- :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithRenderStatic `,
415- which is responsible for calling `renderStatic() ` is deprecated.
416- See section :ref: `migration <fluid-custom-viewhelper-migration >`.
417-
418350.. _render-method :
419351
420352`render() ` method
421353-----------------
422354
423355Most of the time, this method is implemented.
424356
425-
426- .. _fluid-custom-viewhelper-migration :
427-
428- Migration: Remove deprecated compliling traits
429- ==============================================
430-
431- .. _fluid-viewhelper-custom-renderStatic :
432-
433- Migration: Remove deprecated trait `CompileWithRenderStatic `
434- -------------------------------------------------------------
435-
436- To remove the deprecated trait
437- :php: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithRenderStatic ` switch
438- to use the `render() ` method instead of the `renderStatic() `.
439-
440- .. literalinclude :: _CustomViewHelper/MigrateRenderStatic.diff
441- :caption: EXT:my_extension/Classes/ViewHelpers/GravatarViewHelper.php (diff removing CompileWithRenderStatic)
442-
443- *line 13 *
444- Remove the trait :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithRenderStatic `.
445- *lines 23, 24 *
446- Switch the render method from `renderStatic() ` to `render() `.
447- *lines 25, 26 *
448- Fetch the arguments from the class property instead method argument.
449-
450-
451- .. _fluid-custom-viewhelper-CompileWithContentArgumentAndRenderStatic-migration :
452-
453- Migration: Remove deprecated trait `CompileWithContentArgumentAndRenderStatic `
454- ------------------------------------------------------------------------------
455-
456- If :php: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithContentArgumentAndRender `
457- was also used in your ViewHelper implementation, further steps are needed:
458-
459- .. literalinclude :: _CustomViewHelper/_MigrateCompileWithContentArgumentAndRender.diff
460- :caption: EXT:my_extension/Classes/ViewHelpers/GravatarViewHelper.php (diff removing CompileWithContentArgumentAndRender)
461-
462- *line 13 *
463- Remove the trait :php-short: `\T YPO3Fluid\F luid\C ore\V iewHelper\T raits\C ompileWithContentArgumentAndRender `.
464- *lines 22, 23 *
465- Switch the render method from `renderStatic() ` to `render() `.
466- *lines 24, 25 *
467- Use the non-static method :php: `$this->renderChildren() ` instead of the
468- closure `$renderChildrenClosure() `.
469-
470- Remove calls to removed `renderStatic() ` method of another ViewHelper
471- ---------------------------------------------------------------------
472-
473- If you called a now removed `renderStatic() ` method from within another
474- ViewHelper's `renderStatic() ` method you can replace the code like this:
475-
476- .. literalinclude :: _CustomViewHelper/_MigrateRenderStaticInvocation.diff
477- :caption: EXT:my_extension/Classes/ViewHelpers/GravatarViewHelper.php (diff replacing renderStatic() calls)
478-
479- *line 27, 28ff *
480- Replace the static call to the `renderStatic() ` method of another ViewHelper
481- by calling `$this->renderingContext->getViewHelperInvoker()->invoke() ` instead.
482-
483- See also :php: `TYPO3Fluid\F luid\C ore\V iewHelper\V iewHelperInvoker `.
484-
485357.. _fluid-custom-viewhelper-access :
486358
487359How to access classes in the ViewHelper implementation
0 commit comments