Using Fluid ViewHelpers to Keep TYPO3 Templates Clean

Keep TYPO3 Fluid templates clean with custom ViewHelpers

Useful answer: move any PHP‑like logic out of the Fluid file and into a ViewHelper class. The template then only contains markup and simple calls like <f:viewhelperName>.

Worked example: formatting a news date

Assume a controller action that assigns a collection of news records to the view.

public function listAction()
{
    $news = $this->newsRepository->findAll();
    $this->view->assign('newsItems', $news);
}

The corresponding Fluid template (Resources/Private/Templates/News/list.html) can iterate over the collection and delegate date formatting to a ViewHelper.

<f:for each='{newsItems}' as='news'>
    <h2>{news.title}</h2>
    <p>Published: <f:formatDate date='{news.datetime}' /></p>
</f:for>

The formatDate ViewHelper extends \TYPO3\CMS\Fluid\Core\ViewHelper\AbstractViewHelper and implements the render method.

namespace MySite\MyExtension\ViewHelpers;

class FormatDateViewHelper extends \TYPO3\CMS\Fluid\Core\ViewHelper\AbstractViewHelper
{
    public function render($date = null)
    {
        if (!$date instanceof \DateTime) {
            return '';
        }
        return $date->format('d M Y');
    }
}

To make the ViewHelper available, add a namespace declaration at the top of the template.

{namespace fdx=MySite\MyExtension\ViewHelpers}
<f:for each='{newsItems}' as='news'>
    <h2>{news.title}</h2>
    <p>Published: <fdx:formatDate date='{news.datetime}' /></p>
</f:for>

Clearing the cache to see changes

After adding or modifying a ViewHelper, clear the system cache so TYPO3 recompiles the Fluid templates.

# Run from the TYPO3 installation root
typo3cms cache:flush

Required permissions: CLI user that can execute the typo3cms binary (often the deploy or _www user). Expected check: the command finishes without error and returns to the prompt. Risk: flushing the cache forces all pages to be regenerated on the next request, which can cause a short spike in CPU usage.

Limits and common mistakes

• Forgot to register the ViewHelper namespace – the template will show a viewhelper not found exception.
• Putting too much logic in a single ViewHelper can make it hard to test; keep each helper focused on one task.
• Using deeply nested Partials or Sections increases filesystem lookups and can degrade performance on large sites.
• Fluid caches the compiled templates; if you change a ViewHelper class name, you must clear the cache, otherwise the old compiled version is used.
• Directly embedding PHP in a Fluid template is prohibited; any attempt will result in a parsing error.

How to verify the result

1. Reload a page that uses the news list template.
2. View the page source; the date should appear in the format d M Y (e.g., 25 Oct 2026).
3. If the date is missing or shows the raw DateTime object, check the ViewHelper namespace and ensure the cache was flushed.