Tip

Deep nesting is supported: If you want to output the email address of the blog author, then you can use {blog.author.email}, which is roughly equivalent to $blog->getAuthor()->getEmail().

Example 2.1. Tags and Namespace declarations

{namespace f=F3\Fluid\ViewHelpers}⁄
<f:link.action controller="Administration">Administration</f:link.action>

	Namespace Declaration: You import the PHP Namespace F3\Fluid\ViewHelpers under the prefix f. The above namespace import {namespace f=F3\Fluid\ViewHelpers} is imported by default. All other namespaces need to be imported explicitely.[2]
	Calling the View Helper: The <f:link.action...> ... </f:link.action> tag renders a link.

Now, the main difference between Fluid and other templating engines is how the view helpers are implemented: For each view helper, there exists a corresponding PHP class. Let’s see how this works for the example above:

The <f3:link.action /> tag is implemented in the class F3\Fluid\ViewHelpers\Link\ActionViewHelper.

• The first part of the class name is the namespace which was imported (the namespace prefix f was expanded to its full namespace F3\Fluid\ViewHelpers)
• The unqualified name of the tag, without the prefix, is capitalized (Link), and the postfix ViewHelper is appended.

• You cannot override already existing view helpers by accident.
• It is very easy to write custom view helpers, which live next to the standard view helpers
• All user documentation for a view helper can be automatically generated from the annotations and code documentation.

Example 2.2. Creating a link with arguments

<f:link.action controller="Blog" action="show" arguments="{singleBlog: blogObject}">... read more</f:link.action>

Warning

Make sure you do not put a space before or after the opening or closing brackets of an array. If you type arguments=" {singleBlog : blogObject}" (notice the space before the opening curly bracket), the array is automatically casted to a string (as a string concatenation takes place).

This also applies when using object accessors: <f:do.something with="{object}" /> and <f:do.something with=" {object}" /> are substantially different: In the first case, the view helper will receive an object as argument, while in the second case, it will receive a string as argument.

This might first seem like a bug, but actually it is just consistent that it works that way.

Often, you need some kind of conditions inside your template. For them, you will usually use the <f:if> ViewHelper. Now let’s imagine we have a list of blog postings and want to display some additional information for the currently selected blog posting. We assume that the currently selected blog is available in {currentBlogPosting}. Now, let’s have a look how this works:

<f:for each="{blogPosts}" as="post">
  <f:if condition="{post} == {currentBlogPosting}">... some special output here ...</f:if> 
</f:for>

In the above example, there is a bit of new syntax involved: {post} == {currentBlogPosting}. Intuitively, this says “if the post I”m currently iterating over is the same as currentBlogPosting, do something.”

Why can we use this boolean expression syntax? Well, because the IfViewHelper has registered the argument condition as boolean. Thus, the boolean expression syntax is available in all arguments of ViewHelpers which are of type boolean.

All boolean expressions have the form XX Comparator YY, where:

In many cases, the tag-based syntax of ViewHelpers is really intuitive, especially when building loops, or forms. However, in other cases, using the tag-based syntax feels a bit awkward — this can be demonstrated best with the <f:uri.resource>-ViewHelper, which is used to reference static files inside the Public/ folder of a package. That’s why it is often used inside <style> or <script>-tags, leading to the following code:

<link rel="stylesheet" href="<f:uri.resource path='myCssFile.css' />" />

You will notice that this is really difficult to read, as two tags are nested into each other. That’s where the inline notation comes into play: It allows the usage of {f:uri.resource()} instead of <f:uri.resource />. The above example can be written like the following:

<link rel="stylesheet" href="{f:uri.resource(path:'myCssFile.css')}" />

This is readable much better, and explains the intent of the ViewHelper in a much better way: It is used like a helper function.

The syntax is still more flexible: In Real-World templates, you will often find code like the following, formatting a DateTime object (stored in {post.date} in the example below):

<f:format.date format="d-m-Y">{post.date}</f:format.date>

This can also be re-written using the inline notation:

{post.date -> f:format.date(format:'d-m-Y')}

This is also a lot better readable than the above syntax.

To wrap it up: Internally, both syntax variants are handled equally, and every ViewHelper can be called in both ways. However, if the ViewHelper “feels” like a tag, use the tag-based notation, if it “feels” like a helper function, use the Inline Notation.

• a number

  {a : 1,
   b : 2
  }

• a string; Needs to be in either single- or double quotes. In a double-quoted string, you need to escape the ” with a \ in front (and vice versa for single quoted strings). A string is again handled as Fluid Syntax, this is what you see in example c.

  {a : 'Hallo',
   b : "Second string with escaped \" (double quotes) but not escaped ' (single quotes)"
   c : "{firstname} {lastname}"
  }

• a nested array

  {a : {
      a1 : "bla1",
      a2 : "bla2"
    },
   b : "hallo"
  }

• a variable reference (=an object accessor)

  {blogTitle : blog.title,
   blogObject: blog
  }

Example 2.4. An example layout

<html>
<head><title>My fancy web application</title></head>
<body>
<div id="menu">... menu goes here ...</div>
<div id="content">
  <f:render section="content" />
</div>
</body>
</html>

With this tag, a section from the target template is rendered.

• Declare which layout to use: <f:layout name="..." /> can be written anywhere on the page (though we suggest to write it on top, right after the namespace declaration) – the given name references the layout.
• Provide the content for all sections used by the layout using the <f:section>...</f:section> tag: <f:section name="content">...</f3:section>

Example 2.5. A template for the above layout

<f:layout name="example.html" />

<f:section name="content">
This HTML here will be outputted to inside the layout
</f:section>

• $this->arguments is a read-only associative array where you will find the values for all arguments you registered previously.
• $this->renderChildren() renders everything between the opening and closing tag of the view helper and returns the rendered result (as string).
• $this->templateVariableContainer is an instance of F3\Fluid\Core\ViewHelper\TemplateVariableContainer, with which you have access to all variables currently available in the template.

  Additionally, you can add variables to the container with $this->templateVariableContainer->add($identifier, $value), but you have to make sure that you remove every variable you added again! This is a security measure against side-effects.

  It is also not possible to add a variable to the TemplateVariableContainer if a variable of the same name already exists – again to prevent side effects and scope problems.

Example 2.6. Implementing a loop

A loop could be called within the template in the following way:

<f:for each="{blogPosts}" as="blogPost">
  <h2>{blogPost.title}</h2>
</f:for>

So, in words, what should the loop do?

It needs two arguments:

• each: Will be set to some object^[4] which can be iterated over.
• as: The name of a variable which will contain the current element being iterated over

It then should do the following (in pseudocode):

foreach ($each as $$as) {
  // render everything between opening and closing tag
}

Implementing this is fairly straightforward, as you will see right now:

class ForViewHelper {
  /**
   * Renders a loop
   *
   * @param array $each Array to iterate over
   * @param string $as Iteration variable
   */
  public function render(array $each, $as) {
    $out = '';
    foreach ($each as $singleElement) {
      $this->variableContainer->add($as, $singleElement);
      $out .= $this->renderChildren();
      $this->variableContainer->remove($as);
    }
    return $out;
  }
}

	The PHPDoc is part of the code! Fluid extracts the argument datatypes from the PHPDoc.
	You can simply register arguments to the view helper by adding them as method arguments of the render() method.
	Here, everything between the opening and closing tag of the view helper is rendered and returned as string.

The above example demonstrates how we add a variable, render all children (everything between the opening and closing tag), and remove the variable again to prevent side-effects.

• registerTagAttribute($name, $type, $description, $required): Use this method to register an attribute which should be directly added to the tag
• registerUniversalTagAttributes(): If called, registers the standard HTML attributes (class, id, dir, lang, style, title).

Tip

The TagBasedViewHelper also makes sure that all attributes are escaped properly, so to decrease the risk of Cross-Site Scripting attacks, make sure to use it when building tags.

Sometimes, you need some HTML attributes which are not part of the standard. As an example: if you use the Dojo JavaScript framework, using these non-standard attributes makes life a lot easier.^[5]We think that the templating framework should not constrain the user in his possibilities – thus, it should be possible to add custom HTML attributes as well, if they are needed (People who have already worked with JSP know that it can be difficult to archive this. Our solution looks as follows:

Every view helper which inherits from AbstractTagBasedViewHelper has a special property called additionalAttributes which allows you to add arbitary HTML attributes to the tag.

additionalAttributes should be an associative array, where the key is the name of the HTML attribute.

If the link tag from above needed a new attribute called fadeDuration, which is not part of HTML, you could do that as follows:

<f:link.action ... additionalAttributes="{fadeDuration : 800}">Link with fadeDuration set</f:link.action>

This attribute is available in all tags that inherit from F3\Fluid\Core\ViewHelper\AbstractTagBasedViewHelper.

• Two API methods renderThenChild() and renderElseChild(), which should be used in the then / else case.
• The ViewHelper will have two arguments defined, called then and else, which are very helpful in the Inline Notation.
• The ViewHelper will automatically work with the <f:then> and <f:else>-Tags.

All widgets inherit from F3\Fluid\Core\Widget\AbstractWidgetViewHelper. The ViewHelper of the widget is the main entry point; it controls the widget and sets necessary configuration for the widget.

To implement your own widget, the following things need to be done:

By default, all ViewHelper arguments are stored as Widget Configuration, and are also available inside the Widget Controller. However, to modify the Widget Configuration, you can override the getWidgetConfiguration() method and return the configuration which you need there.

There is also a property $ajaxWidget, which we will explain later in the section “Ajax Widgets”.

A widget contains one controller, which must inherit from F3\Fluid\Core\Widget\AbstractWidgetController, which is an ActionController. There is only one difference between the normal ActionController which you are used to, and the AbstractWidgetController, which is the property $widgetConfiguration, containing the Widget’s configuration which was set in the ViewHelper.

The Fluid templates of a widget are normal Fluid templates as you know them, but have a few ViewHelpers available additionally, which are described below:

Widgets have special support for AJAX functionality. We’ll first explain what needs to be done to create an AJAX compatible widget, and then explain it with an example.

To make a widget AJAX-aware, you need to do the following:

<f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo">{foo}</f:for>

Output:

1234

<ul>
   <f:for each="{fruit1: 'apple', fruit2: 'pear', fruit3: 'banana', fruit4: 'cherry'}" as="fruit" key="label">
     <li>{label}: {fruit}</li>
   </f:for>
 </ul>

Output:

<ul>

<li>fruit1: apple</li>

<li>fruit2: pear</li>

<li>fruit3: banana</li>

<li>fruit4: cherry</li>

</ul>

<f:alias map="{x: 'foo'}">{x}</f:alias>

<output>

foo

</output>

<f:alias map="{x: foo.bar.baz, y: foo.bar.baz.name}">
   {x.name} or {y}
 </f:alias>

<output>

[name] or [name]

depending on {foo.bar.baz}

</output>

<f:base />

<output>

<base href=”http://yourdomain.tld/”></base>

(depending on your domain)

</output>

No arguments defined.

<f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo"><f:cycle values="{0: 'foo', 1: 'bar', 2: 'baz'}" as="cycle">{cycle}</f:cycle></f:for>

<output>

foobarbazfoo

</output>

<ul>
   <f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo">
     <f:cycle values="{0: 'odd', 1: 'even'}" as="zebraClass">
       <li>{foo}</li>
     </f:cycle>
   </f:for>
 </ul>

<output>

<ul>

<li>1</li>

<li>2</li>

<li>3</li>

<li>4</li>

</ul>

</output>

No arguments defined.

<f:flashMessages />

Renders an ul-list of flash messages.

<f:flashMessages />

Output:

<ul>

…

</ul>

<f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo">{foo}</f:for>

<output>

1234

</output>

<ul>
   <f:for each="{fruit1: 'apple', fruit2: 'pear', fruit3: 'banana', fruit4: 'cherry'}" as="fruit" key="label">
     <li>{label}: {fruit}</li>
   </f:for>
 </ul>

<output>

<ul>

<li>fruit1: apple</li>

<li>fruit2: pear</li>

<li>fruit3: banana</li>

<li>fruit4: cherry</li>

</ul>

</output>

Use <f:form> to output an HTML <form> tag which is targeted at the specified action, in the current controller and package.

It will submit the form data via a POST request. If you want to change this, use method=”get” as an argument.

<f:form action="...">...</f:form>

<f:form action="..." name="customer" object="{customer}">
   <f:form.hidden property="id" />
   <f:form.textbox property="name" />
 </f:form>

This automatically inserts the value of {customer.name} inside the textbox and adjusts the name of the textbox accordingly.

<f:form.checkbox name="myCheckBox" value="someValue" />

Output:

<input type=”checkbox” name=”myCheckBox” value=”someValue” />

<f:form.checkbox name="myCheckBox" value="someValue" checked="{object.value} == 5" />

Output:

<input type=”checkbox” name=”myCheckBox” value=”someValue” checked=”checked” />

(depending on $object)

<f:form.checkbox property="interests" value="TYPO3" />

Output:

<input type=”checkbox” name=”user[interests][]” value=”TYPO3″ checked=”checked” />

(depending on property “interests”)

<ul>
   <f:errors>
     <li>{error.code}: {error.message}</li>
   </f:errors>
 </ul>

Output:

<ul>

<li>1234567890: Validation errors for argument “newBlog”</li>

</ul>

<f:hidden name="myHiddenValue" value="42" />

Output:

<input type=”hidden” name=”myHiddenValue” value=”42″ />

You can also use the “property” attribute if you have bound an object to the form.

See <f:form> for more documentation.

<f:form.password name="myPassword" />

Output:

<input type=”password” name=”myPassword” value=”default value” />

<f:form.radio name="myRadioButton" value="someValue" />

Output:

<input type=”radio” name=”myRadioButton” value=”someValue” />

<f:form.radio name="myRadioButton" value="someValue" checked="{object.value} == 5" />

Output:

<input type=”radio” name=”myRadioButton” value=”someValue” checked=”checked” />

(depending on $object)

<f:form.radio property="newsletter" value="1" /> yes
 <f:form.radio property="newsletter" value="0" /> no

Output:

<input type=”radio” name=”user[newsletter]” value=”1″ checked=”checked” /> yes

<input type=”radio” name=”user[newsletter]” value=”0″ /> no

(depending on property “newsletter”)

The most straightforward way is to supply an associative array as the “options” parameter.

The array key is used as option key, and the value is used as human-readable name.

<f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" />

To pre-select a value, set “value” to the option key which should be selected.

<f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" value="visa" />

Generates a dropdown box like above, except that “VISA Card” is selected.

If the select box is a multi-select box (multiple=”true”), then “value” can be an array as well.

If you want to output domain objects, you can just pass them as array into the “options” parameter.

To define what domain object value should be used as option key, use the “optionValueField” variable. Same goes for optionLabelField.

If neither is given, the Identifier (UUID/uid) and the __toString() method are tried as fallbacks.

If the optionValueField variable is set, the getter named after that value is used to retrieve the option key.

If the optionLabelField variable is set, the getter named after that value is used to retrieve the option value.

<f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />

In the above example, the userArray is an array of “User” domain objects, with no array key specified.

So, in the above example, the method $user->getId() is called to retrieve the key, and $user->getFirstName() to retrieve the displayed value of each entry.

The “value” property now expects a domain object, and tests for object equivalence.

<f:submit value="Send Mail" />

Output:

<input type=”submit” />

<f:submit name="mySubmit" value="Send Mail"><button>dummy button</button></f:submit>

Output:

<input type=”submit” name=”mySubmit” value=”Send Mail” />

<f:textarea name="myTextArea" value="This is shown inside the textarea" />

Output:

<textarea name=”myTextArea”>This is shown inside the textarea</textarea>

<f:textbox name="myTextBox" value="default value" />

Output:

<input type=”text” name=”myTextBox” value=”default value” />

<f:upload name="file" />

Output:

<input type=”file” name=”file” />

<f:format.crop maxCharacters="10">This is some very long text</f:format.crop>

Output:

This is so…

<f:format.crop maxCharacters="17" append=" [more]">This is some very long text</f:format.crop>

Output:

This is some very [more]

WARNING: This tag does NOT handle tags currently.

WARNING: This tag doesn’t care about multibyte charsets currently.

<f:format.currency>123.456</f:format.currency>

Output:

123,46

<f:format.currency currencySign="$" decimalSeparator="." thousandsSeparator=",">54321</f:format.currency>

Output:

54,321.00 $

<f:format.date>{dateObject}</f:format.date>

Output:

1980-12-13

(depending on the current date)

<f:format.date format="H:i">{dateObject}</f:format.date>

Output:

01:23

(depending on the current time)

<f:format.date format="d.m.Y - H:i:s">+1 week 2 days 4 hours 2 seconds</f:format.date>

Output:

13.12.1980 – 21:03:42

(depending on the current time, see http://www.php.net/manual/en/function.strtotime.php)

No arguments defined.

<f:format.printf arguments="{number : 362525200}">%.3e</f:format.printf>

Output:

3.625e+8

<f:format.printf arguments="{0: 3,1: 'Kasper'}">%2$s is great, TYPO%1$d too. Yes, TYPO%1$d is great and so is %2$s!</f:format.printf>

Output:

Kasper is great, TYPO3 too. Yes, TYPO3 is great and so is Kasper!

<f:format.printf arguments="{1:'TYPO3'}">We love %s</f:format.printf>

Output:

We love TYPO3

<f:groupedFor each="{0: {name: 'apple', color: 'green'}, 1: {name: 'cherry', color: 'red'}, 2: {name: 'banana', color: 'yellow'}, 3: {name: 'strawberry', color: 'red'}}" as="fruitsOfThisColor" groupBy="color">
   <f:for each="{fruitsOfThisColor}" as="fruit">
     {fruit.name}
   </f:for>
 </f:groupedFor>

Output:

apple cherry strawberry banana

<ul>
   <f:groupedFor each="{0: {name: 'apple', color: 'green'}, 1: {name: 'cherry', color: 'red'}, 2: {name: 'banana', color: 'yellow'}, 3: {name: 'strawberry', color: 'red'}}" as="fruitsOfThisColor" groupBy="color" groupKey="color">
     <li>
       {color} fruits:
       <ul>
         <f:for each="{fruitsOfThisColor}" as="fruit" key="label">
           <li>{label}: {fruit.name}</li>
         </f:for>
       </ul>
     </li>
   </f:groupedFor>
 </ul>

Output:

<ul>

<li>green fruits

<ul>

<li>0: apple</li>

</ul>

</li>

<li>red fruits

<ul>

<li>1: cherry</li>

</ul>

<ul>

<li>3: strawberry</li>

</ul>

</li>

<li>yellow fruits

<ul>

<li>2: banana</li>

</ul>

</li>

</ul>

Example 2.50. Example

<f:layout name="main" />

<f:link.action>some link</f:link.action>

Output:

<a href=”documentation/manuals/fluid/currentpackage%2Fcurrentcontroller/”>some link</a>

(depending on routing setup and current package/controller/action)

<f:link.action action="myAction" controller="MyController" package="MyPackage" subpackage="MySubpackage" arguments="{key1: 'value1', key2: 'value2'}">some link</f:link.action>

Output:

<a href=”documentation/manuals/fluid/mypackage%2Fmycontroller%2Fmysubpackage%2Fmyaction%3Fkey1%3Dvalue1%26amp%3Bamp%3Bkey2%3Dvalue2/”>some link</a>

(depending on routing setup)

<code title=”basic email link”>

<f:link.external uri="http://www.typo3.org" target="_blank">external link</f:link.external>

Output:

<a href=”http://www.typo3.org” target=”_blank”>external link</a>

<f:security.ifAccess resource="someResource">
   This is being shown in case you have access to the given resource
 </f:security.ifAccess>

Everything inside the <f:ifAccess> tag is being displayed if you have access to the given resource.

<f:security.ifAccess resource="someResource">
   <f:then>
     This is being shown in case you have access.
   </f:then>
   <f:else>
     This is being displayed in case you do not have access.
   </f:else>
 </f:security.ifAccess>

Everything inside the “then” tag is displayed if you have access.

Otherwise, everything inside the “else”-tag is displayed.

<f:security.ifHasRole role="Administrator">
   This is being shown in case you have the Administrator role (aka role).
 </f:security.ifHasRole>

Everything inside the <f:ifHasRole> tag is being displayed if you have the given role.

<f:security.ifHasRole role="Administrator">
   <f:then>
     This is being shown in case you have the role.
   </f:then>
   <f:else>
     This is being displayed in case you do not have the role.
   </f:else>
 </f:security.ifHasRole>

Everything inside the “then” tag is displayed if you have the role.

Otherwise, everything inside the “else”-tag is displayed.

No arguments defined.

<f:uri.action>some link</f:uri.action>

Output:

currentpackage/currentcontroller

(depending on routing setup and current package/controller/action)

<f:uri.action action="myAction" controller="MyController" package="MyPackage" subpackage="MySubpackage" arguments="{key1: 'value1', key2: 'value2'}">some link</f:uri.action>

Output:

mypackage/mycontroller/mysubpackage/myaction?key1=value1&amp;key2=value2

(depending on routing setup)

<code title=”basic email uri”>

<f:uri.external uri="http://www.typo3.org" />

Output:

http://www.typo3.org

<link href="documentation/manuals/fluid/%7Bf%3Auri.resource%28%27css%2Fstylesheet.css%27%29%7D/" rel="stylesheet" />

Output:

<link href=”Resources/Packages/MyPackage/stylesheet.css” rel=”stylesheet” />

(depending on current package)

<k:inflect.humanizeCamelCase>{CamelCasedModelName}</k:inflect.humanizeCamelCase>

Output:

Camel cased model name

<k:inflect.pluralize>foo</k:inflect.pluralize>

Output:

foos

No arguments defined.

<k:rawValue>{textWith>Add>AndStuff}</k:rawValue>

Output:

textWith>Add>AndStuff

No arguments defined.

No arguments defined.