Writing a basic Fluid ViewHelper for TYPO3

By Steffen Müller. Licensed under the Creative Commons License

After listening to Sebastians talk at T3DD09 today about the new templating engine Fluid, I felt inspired to give it a try. I am really surprised how easy it is to extend Fluid by writing an own ViewHelper. Read on to learn how to get started. [Update 2009/12/23: now using 4.3 stable API]

My goal was to add a Fluid ViewHelper to the blog_example extension. This extension is backported from FLOW3 to TYPO3 v.4 as a demonstration for extBase. Read more about blog_example, extBase and Fluid in v.4 in the MVC framework project page. I will not explain details here but concentrate on the view helper stuff. My view helper should add a new template marker which creates a dummy text "Lorem Ipsum". The marker expects an integer value, which is used for cropping the dummy text.

After installing and setting up extBase, Fluid and the blog_example extensions, I added a new view helper folder in the blog_example extension:

mkdir typo3conf/ext/blog_example/Classes/ViewHelpers

This folder is generally used as a container for view helpers which are shipped with extensions. In the next step, I created a new which contains the helper itself:

touch typo3conf/ext/blog_example/Classes/ViewHelpers/LoremIpsumViewHelper.php

It's important to stick to this naming scheme, because otherwise Fluid will not find the view helper. Let's have a closer look at it. Beside the .php extension at the end of the filename, it contains two main parts: LoremIpsum and ViewHelper. LoremIpsum is the very name of the view helper and ViewHelper is a constant which is a mandatory part. The filename reflects the naming scheme of the class name of the view helper. So let's see what the file content looks like. I removed some comments to increase readability:

<?php

/**
 * This class is a demo view helper for the Fluid templating engine.
 *
 * @package TYPO3
 * @subpackage Fluid
 * @version
 */
class Tx_BlogExample_ViewHelpers_LoremIpsumViewHelper extends Tx_Fluid_Core_ViewHelper_AbstractViewHelper {

    /**
     * Renders some classic dummy content: Lorem Ipsum...
     *
     * @param int $length The number of characters of the dummy content
     * @validate $length IntegerValidator
     * @return string dummy content, cropped after the given number of characters
     * @author Lorem Ipsum <lorem@example.com>
     */
    public function render($length) {
        $dummyContent = 'Lorem ipsum dolor sit amet.';
        return substr($dummyContent, 0, $length);
    }
}

?>

This is a very basic example. My class extends the abstract view helper class of Fluid. I will not explain the Fluid API here. Let's concentrate on the example. The only method of my class is render() which is used to render the content of my marker. It crops a "Lorem Ipsum" string to a given length by using the substr() function. Some PHPDoc parts in the comments of the render() method are mandatory to get the view helper working. For example the @param part defines the argument and its type (int). Other PHPDoc parts are optional, like @validate. This argument ensures that the render() method only gets integer values. The validation itself is performed by the Extbase framework, so you don't have to care. If you'd like to learn more about validators, have a look at the PHP files in extbase/Classes/Validation/Validator/. That's all for this part of fluid.

In a next step, I've added the view helper to the Fluid template of blog_example:

# vi typo3conf/ext/blog_example/Resources/Private/Templates/Blog/index.html

First I had to declare a namespace for my view helpers. I do this at the top of the template file. I chose to use blog, to be used as a shortcut to all the view helpers of the blog_example extension. Next is the marker itself. I put the marker below the existing <f:layout> and <f:section> tags. The syntax of my new marker is easy to spot: The namespace and the viewhelper name is seperated by a : The length arguments is given afterwards:

{namespace blog=Tx_BlogExample_ViewHelpers} 

<f:layout name="default" />
<f:section name="content">

<h1>
  <blog:loremIpsum length="5" />
</h1>

The result of using this template marker is a level 1 header with "Lorem" as the text:

<h1>Lorem</h1>

That's all. I am really exited about how easy it is to write own view helpers. I hope this article could demonstrate that and motivate you to get into the FLOW3/Fluid/extBase universe.

--> Back to the list of articles