菜单

Fluid User Manual

2011年04月4日 - Extbase/Fluid

This chapter describes all things the users of the templating system needs to know. After you’ve read the introduction, you can dive into the concepts of Fluid which are relevant to you.

The chapter starts with an overview of basic concepts, continues with using layouts, and finishes with how to write your own view helpers.

2.1. Basic concepts

This section describes all basic concepts available.

This includes:

  • Variables / Object Accessors
  • View Helpers
  • Arrays

Variables and Object Accessors

A templating system would be quite pointless if it was not possible to display some external data in the templates. That’s what variables are for:

Suppose you want to output the title of your blog, you could write the following snippet into your controller:

$this->view->assign('blogTitle', $blog->getTitle());

Then, you could output the blog title in your template with the following snippet:

<h1>This blog is called {blogTitle}</h1>

Now, you might want to extend the output by the blog author as well. To do this, you could repeat the above steps, but that would be quite inconvenient and hard to read. [1]

That’s why the template language has a special syntax for object access, demonstrated below. A nicer way of expressing the above is the following:

This should go into the controller:
$this->view->assign('blog', $blog);
This should go into the template:
<h1>This blog is called {blog.title}, written by {blog.author}</h1>

Instead of passing strings to the template, we are passing whole objects around now – which is much nicer to use both from the controller and the view side. To access certain properties of these objects, you can use Object Accessors. By writing {blog.title}, the template engine will call a getTitle() method on the blog object, if it exists. Besides, you can use that syntax to traverse associative arrays and public properties.

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().

View Helpers

All output logic is placed in View Helpers.

The view helpers are invoked by using XML tags in the template, and are implemented as PHP classes (more on that later).

This concept is best understood with an example:

Example 2.1. Tags and Namespace declarations

{namespace f=F3\Fluid\ViewHelpers}⁄1
<f:link.action controller="Administration">Administration</f:link.action>2
1 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]
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 class name of such a view helper is constructed for a given tag as follows:

  • 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.

The tag and view helper concept is the core concept of Fluid. All output logic is implemented through such ViewHelpers / Tags! Things like if/else, for, … are all implemented using custom tags – a main difference to other templating languages.

Some benefits of this approach are:

  • 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.

Most view helpers have some parameters. These can be plain strings, just like in <f:link.action controller="Administration">...</f:link.action>, but as well arbitary objects. Parameters of view helpers will just be parsed with the same rules as the rest of the template, thus you can pass arrays or objects as parameters.

This is often used when adding arguments to links:

Example 2.2. Creating a link with arguments

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

Here, the view helper will get a parameter called arguments which is of type array.

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.

Boolean expressions

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:

Example 2.3. Using boolean expressions

<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:

  • Comparator is one of the following: ==, >, >=, <, <=, % (modulo)
  • XX / YY is one of the following:
    • A number (integer or float
    • A JSON Array
    • A ViewHelper
    • An Object Accessor (this is probably the most used example)

Inline Notation for ViewHelpers

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.

Tip

This can also be nested indefinitely often, so one can write: {post.date -> foo:myHelper() -> bar:bla()}

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.

Arrays

Some view helpers, like the SelectViewHelper (which renders an HTML select dropdown box), need to get associative arrays as arguments (mapping from internal to displayed name). See the following example how this works:

<f:form.select options="{edit: 'Edit item', delete: 'Delete item'}" />

The array syntax used here is very similar to the JSON object syntax. Thus, the left side of the associative array is used as key without any parsing, and the right side can be either:

  • 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
    }

2.2. Passing data to the view

You can pass arbitary objects to the view, using $this->view->assign(⁄IdentifierString, ⁄Object) from within the controller. See the above paragraphs about Object Accessors for details how to use the passed data.

2.3. Layouts

In almost all web applications, there are many similarities between each page. Usually, there are common templates or menu structures which will not change for many pages.

To make this possible in Fluid, we created a layout system, which we will introduce in this section.

Writing a layout

Every layout is placed in the Resources/Private/Layouts directory, and has the file ending .html. A layout is a normal Fluid template file, except there are some parts where the actual content of the target page should be inserted.

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" />1
</div>
</body>
</html>
1 With this tag, a section from the target template is rendered.

Using a layout

Using a layout involves two steps:

  • 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>

For the above layout, a minimal template would look like the following:

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>

2.4. Writing your own View Helper

As we have seen before, all output logic resides in View Helpers. This includes the standard control flow operators such as if/else, HTML forms, and much more. This is the concept which makes Fluid extremely versatile and extensible.

If you want to create a view helper which you can call from your template (as a tag), you just write a plain PHP class which needs to inherit from F3\Fluid\Core\AbstractViewHelper (or its subclasses). You need to implement only one method to write a view helper:

public function render()

Rendering the View Helper

We refresh what we have learned so far: When a user writes something like <blog:displayNews /> inside a template (and has imported the “blog” namespace to F3\Blog\ViewHelpers), Fluid will automatically instanciate the class F3\Blog\ViewHelpers\DisplayNewsViewHelper, and invoke the render() method on it.

This render() method should return the rendered content as string.

You have the following possibilities to access the environment when rendering your view helper:

  • $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.

Now, we will look at an example: How to write a view helper giving us the foreach functionality of PHP.[3]

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 over1
   * @param string $as Iteration variable
   */
  public function render(array $each, $as) {2
    $out = '';
    foreach ($each as $singleElement) {
      $this->variableContainer->add($as, $singleElement);
      $out .= $this->renderChildren();3
      $this->variableContainer->remove($as);
    }
    return $out;
  }
}
1 The PHPDoc is part of the code! Fluid extracts the argument datatypes from the PHPDoc.
2 You can simply register arguments to the view helper by adding them as method arguments of the render() method.
3 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.

Declaring arguments

We have now seen that we can add arguments just by adding them as method arguments to the render() method. There is, however, a second method to register arguments:

You can also register arguments inside a method called initializeArguments(). Call $this->registerArgument($name, $dataType, $description, $isRequired, $defaultValue=NULL) inside.

It depends how many arguments a view helper has. Sometimes, registering them as render() arguments is more beneficial, and sometimes it makes more sense to register them in initializeArguments().

AbstractTagBasedViewHelper

Many view helpers output an HTML tag – for example <f3:link.action ...> outputs a <a href="..."> tag. There are many ViewHelpers which work that way.

Very often, you want to add a CSS class or a target attribute to an <a href="..."> tag. This often leads to repetitive code like below. (Don’t look at the code too thoroughly, it should just demonstrate the boring and repetitive task one would have without the AbstractTagBasedViewHelper).

class LinkViewHelper extends \F3\Fluid\Core\AbstractViewHelper {
  public function initializeArguments() {
    $this->registerArgument('class', 'string', 'CSS class to add to the link');
    $this->registerArgument('target', 'string', 'Target for the link');
    ... and more ...
  }
  public function render() {
    $output = '<a href="..."';
    if ($this->arguments['class']) {
      $output .= '';
    }
    if ($this->arguments['target']) {
      $output .= ' target="' . $this->arguments['target'] . '"';
    }
    $output .= '>';
    ... and more ...
    return $output;
  }
}

Now, the AbstractTagBasedViewHelper introduces two more methods you can use inside initializeArguments():

  • 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).

Inside the AbstractTagBasedViewHelper, there is a TagBuilder object available (with $this->tag) which makes building a tag a lot more straightforward

With the above methods we get, the LinkViewHelper from above can be condensed as follows:

class LinkViewHelper extends \F3\Fluid\Core\AbstractViewHelper {
	public function initializeArguments() {
		$this->registerUniversalTagAttributes();
	}

	/**
	 * Render the link.
	 *
	 * @param string $action Target action
	 * @param array $arguments Arguments
	 * @param string $controller Target controller. If NULL current controllerName is used
	 * @param string $package Target package. if NULL current package is used
	 * @param string $subpackage Target subpackage. if NULL current subpackage is used
	 * @param string $section The anchor to be added to the URI
	 * @return string The rendered link
	 */
	public function render($action = NULL, array $arguments = array(), $controller = NULL, $package = NULL, $subpackage = NULL, $section = '') {
		$uriBuilder = $this->controllerContext->getURIBuilder();
		$uri = $uriBuilder->URIFor($action, $arguments, $controller, $package, $subpackage, $section);
		$this->tag->addAttribute('href', $uri);
		$this->tag->setContent($this->renderChildren());

		return $this->tag->render();
	}
}

Additionally, we now already have support for all universal HTML attributes.

You might now think that the building blocks are ready, but there is one more nice thing to add: additionalAttributes! Read about it in the next section.

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.

additionalAttributes

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.

AbstractConditionViewHelper

If you want to build some kind of if/else condition, you should base the ViewHelper on the AbstractConditionViewHelper, as it gives you convenient methods to render the then or else-parts of a ViewHelper. Let’s look at the <f:if>-ViewHelper for a usage example, which should be quite self-explanatory:

<?php
class IfViewHelper extends \F3\Fluid\Core\ViewHelper\AbstractConditionViewHelper {

	/**
	 * renders <f:then> child if $condition is true, otherwise renders <f:else> child.
	 *
	 * @param boolean $condition View helper condition
	 * @return string the rendered string
	 * @author Sebastian Kurfürst <sebastian@typo3.org>
	 * @author Bastian Waidelich <bastian@typo3.org>
	 * @api
	 */
	public function render($condition) {
		if ($condition) {
			return $this->renderThenChild();
		} else {
			return $this->renderElseChild();
		}
	}
}
?>

By basing your condition ViewHelper on the AbstractConditionViewHelper, you will get the following features:

  • 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.

2.5. Widgets

Widgets are special ViewHelpers which encapsulate complex functionality. It can be best understood what widgets are by giving some examples:

  • <f:widget.paginate> renders a Paginator, i.e. can be used to display large amounts of objects. This is best known from search engines.
  • <f:widget.autocomplete> adds autocompletion functionality to a text field.
  • More widgets could include a Google Maps widget, a sortable grid, …

Internally, widgets consist of an own Controller and View part.

Using Widgets

Using widgets inside your templates is really simple: Just use them like standard ViewHelpers, and consult their documentation for usage examples. An example for the <f:widget.paginate> follows below:

<f:widget.paginate itemsPerPage="10" objects="{blogs}" as="paginatedBlogs">
  // use {paginatedBlogs} as you used {blogs} before, most certainly inside
  // a <f:for> loop.
</f:widget.paginate>

In the above example, it looks like {blogs} contains all Blog objects, thus you might wonder if all objects were fetched from the database. However, the blogs are NOT fetched from the database until you actually use them, so the paginate ViewHelper will adjust the query sent to the database and receive only the small subset of objects. So, there is no negative performance overhead in using the Paginate Widget.

Writing widgets

We already mentioned that a widget consists of a controller and a view, all triggered by a ViewHelper. We’ll now explain these different components one after each other, explaining the API you have available for creating your own widgets.

ViewHelper

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:

  • The controller of the widget needs to be injected into the $controller property.
  • Inside the render()-method, you should call $this->initiateSubRequest(), which will initiate a request to the controller which is set in the $controller property, and return the Response object.

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”.

Controller

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.

Fluid Template

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:

  • <f:uri.widget>: Generates an URI to another action of the widget.
  • <f:link.widget>: Generates a link to another action of the widget.
  • <f:renderChildren>: Can be used to render the child nodes of the Widget ViewHelper, possibly with some more variables declared.

Ajax Widgets

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:

  • set $ajaxWidget to TRUE inside the ViewHelper. This will generate an unique AJAX Identifier for the Widget, and store the WidgetConfiguration in the user’s session on the server.
  • Inside the index-action of the Widget Controller, generate the JavaScript which triggers the AJAX functionality. There, you will need a URI which returns the AJAX response. For that, use <f:uri.widget ajax="TRUE" action="..." arguments="..." /> inside the template.
  • Inside the template of the AJAX request, <f:renderChildren> is not available, because the child nodes of the Widget ViewHelper are not accessible there.

2.6. Standard View Helper Library

Should be autogenerated from the tags.

ers.

Formats a string using PHPs str_pad function.

Arguments

Table 2.1. Arguments

Name Type Required Description Default
padLength integer yes Length of the resulting string. If the value of pad_length is negative or less than the length of the input string, no padding takes place.
padString string no The padding string

ers.groupedFor

Loop view helper

Examples

Example 2.7. Simple

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

Output:

1234

Example 2.8. Output array key

<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>

Arguments

Table 2.2. Arguments

Name Type Required Description Default
each array yes The array to be iterated over
as string yes The name of the iteration variable
groupBy string yes Group by this property
groupKey string no The name of the variable to store the current group groupKey

ers.linkIssues

Link issues view helper

Arguments

Table 2.3. Arguments

Name Type Required Description Default
baseUri string yes
pattern string no /#([0-9]+)/

alias

Declares new variables which are aliases of other variables.

Takes a “map”-Parameter which is an associative array which defines the shorthand mapping.

The variables are only declared inside the <f:alias>…</f:alias>-tag. After the

closing tag, all declared variables are removed again.

Examples

Example 2.9. Single alias

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

<output>

foo

</output>

Example 2.10. Multiple mappings

<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>

Arguments

Table 2.4. Arguments

Name Type Required Description Default
map array yes

base

View helper which creates a <base href=”documentation/manuals/fluid/…/”></base> tag. The Base URI

is taken from the current request.

In FLOW3, you should always include this ViewHelper to make the links work.

Examples

Example 2.11. Example

<f:base />

<output>

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

(depending on your domain)

</output>

Arguments

No arguments defined.

cycle

This ViewHelper cycles through the specified values.

This can be often used to specify CSS classes for example.

Examples

Example 2.12. Simple

<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>

Example 2.13. Alternating CSS class

<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>

Arguments

Table 2.5. Arguments

Name Type Required Description Default
values array yes The array or \SplObjectStorage to iterated over
as string yes The name of the iteration variable

else

Else-Branch of a condition. Only has an effect inside of “If”. See the If-ViewHelper for documentation.

Arguments

No arguments defined.

flashMessages

View helper which renders the flash messages (if there are any) as an unsorted list.

In case you need custom Flash Message HTML output, please write your own ViewHelper for the moment.

Examples

Example 2.14. Simple

<f:flashMessages />

Renders an ul-list of flash messages.

Example 2.15. Output with css class

<f:flashMessages />

Output:

<ul>

</ul>

Arguments

Table 2.6. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

for

Loop view helper which can be used to interate over array.

Implements what a basic foreach()-PHP-method does.

Examples

Example 2.16. Simple Loop

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

<output>

1234

</output>

Example 2.17. Output array key

<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>

Arguments

Table 2.7. Arguments

Name Type Required Description Default
each array yes The array or \SplObjectStorage to iterated over
as string yes The name of the iteration variable
key string no The name of the variable to store the current array key
reverse boolean no If enabled, the iterator will start with the last element and proceed reversely

form

Form view helper. Generates a <form> Tag.

Basic usage

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.

Example 2.18. Example

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

A complex form with a specified encoding type

Example 2.19. Form with enctype set

<f:form action=".." controllerName="..." packageName="..." enctype="multipart/form-data">...</f:form>

A Form which should render a domain object

Example 2.20. Binding a domain object to a 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.

Arguments

Table 2.8. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
action string no target action
arguments array no additional arguments Array
controller string no name of target controller
package string no name of target package
subpackage string no name of target subpackage
object mixed no object to use for the form. Use in conjunction with the “property” attribute on the sub tags
section string no The anchor to be added to the URI
fieldNamePrefix string no Prefix that will be added to all field names within this form
actionUri string no can be used to overwrite the “action” attribute of the form tag
enctype string no MIME type with which the form is submitted
method string no Transfer type (GET or POST)
name string no Name of form
onreset string no JavaScript: On reset of the form
onsubmit string no JavaScript: On submit of the form
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.checkbox

View Helper which creates a simple checkbox (<input type=”checkbox”>).

Examples

Example 2.21. Example

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

Output:

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

Example 2.22. Preselect

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

Output:

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

(depending on $object)

Example 2.23. Bind to object property

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

Output:

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

(depending on property “interests”)

Arguments

Table 2.9. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
checked boolean no Specifies that the input element should be preselected
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
disabled string no Specifies that the input element should be disabled when the page loads
errorClass string no CSS class to set if there are errors for this view helper f3-form-error
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.errors

Error messages view helper

Examples

Example 2.24. Output error messages as a list

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

Output:

<ul>

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

</ul>

Arguments

Table 2.10. Arguments

Name Type Required Description Default
for string no The name of the error name (e.g. argument name or property name)
as string no The name of the variable to store the current error error

form.hidden

Renders an <input type=”hidden” …> tag.

Examples

Example 2.25. Example

<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.

Arguments

Table 2.11. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.password

View Helper which creates a simple Password Text Box (<input type=”password”>).

Examples

Example 2.26. Example

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

Output:

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

Arguments

Table 2.12. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
disabled string no Specifies that the input element should be disabled when the page loads
maxlength int no The maxlength attribute of the input field (will not be validated)
readonly string no The readonly attribute of the input field
size int no The size of the input field
errorClass string no CSS class to set if there are errors for this view helper f3-form-error
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.radio

View Helper which creates a simple radio button (<input type=”radio”>).

Examples

Example 2.27. Example

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

Output:

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

Example 2.28. Preselect

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

Output:

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

(depending on $object)

Example 2.29. Bind to object property

<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”)

Arguments

Table 2.13. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
checked boolean no Specifies that the input element should be preselected
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
disabled string no Specifies that the input element should be disabled when the page loads
errorClass string no CSS class to set if there are errors for this view helper f3-form-error
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.select

This view helper generates a <select> dropdown list for the use with a form.

Basic usage

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.

Example 2.30. Basic usage

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

Pre-select a value

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

Example 2.31. Default value

<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.

Usage on domain objects

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.

Example 2.32. Domain objects

<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.

Arguments

Table 2.14. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element
multiple string no if set, multiple select field
size string no Size of input field
disabled string no Specifies that the input element should be disabled when the page loads
options array yes Associative array with internal IDs as key, and the values are displayed in the select box
optionValueField string no If specified, will call the appropriate getter on each object to determine the value.
optionLabelField string no If specified, will call the appropriate getter on each object to determine the label.
errorClass string no CSS class to set if there are errors for this view helper f3-form-error

form.submit

Creates a submit button.

Examples

Example 2.33. Defaults

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

Output:

<input type=”submit” />

Example 2.34. Dummy content for template preview

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

Output:

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

Arguments

Table 2.15. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
disabled string no Specifies that the input element should be disabled when the page loads
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.textarea

Textarea view helper.

The value of the text area needs to be set via the “value” attribute, as with all other form ViewHelpers.

Examples

Example 2.35. Example

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

Output:

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

Arguments

Table 2.16. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
rows int yes The number of rows of a text area
cols int yes The number of columns of a text area
disabled string no Specifies that the input element should be disabled when the page loads
errorClass string no CSS class to set if there are errors for this view helper f3-form-error
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.textbox

View Helper which creates a simple Text Box (<input type=”text”>).

Examples

Example 2.36. Example

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

Output:

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

Arguments

Table 2.17. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
disabled string no Specifies that the input element should be disabled when the page loads
maxlength int no The maxlength attribute of the input field (will not be validated)
readonly string no The readonly attribute of the input field
size int no The size of the input field
errorClass string no CSS class to set if there are errors for this view helper f3-form-error
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

form.upload

A view helper which generates an <input type=”file”> HTML element.

Make sure to set enctype=”multipart/form-data” on the form!

Examples

Example 2.37. Example

<f:upload name="file" />

Output:

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

Arguments

Table 2.18. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
name string no Name of input tag
value mixed no Value of input tag
property string no Name of Object Property. If used in conjunction with <f:form object=”…”>, “name” and “value” properties will be ignored.
disabled string no Specifies that the input element should be disabled when the page loads
errorClass string no CSS class to set if there are errors for this view helper f3-form-error
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element

format.crop

Use this view helper to crop the text between its opening and closing tags.

Examples

Example 2.38. Defaults

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

Output:

This is so…

Example 2.39. Custom suffix

<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.

Arguments

Table 2.19. Arguments

Name Type Required Description Default
maxCharacters integer yes Place where to truncate the string
append string no What to append, if truncation happened

format.currency

Formats a given float to a currency representation.

Examples

Example 2.40. Defaults

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

Output:

123,46

Example 2.41. All parameters

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

Output:

54,321.00 $

Arguments

Table 2.20. Arguments

Name Type Required Description Default
currencySign string no (optional) The currency sign, eg $ or €.
decimalSeparator string no (optional) The separator for the decimal point. ,
thousandsSeparator string no (optional) The thousands separator. .

format.date

Formats a \DateTime object.

Examples

Example 2.42. Defaults

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

Output:

1980-12-13

(depending on the current date)

Example 2.43. Custom date format

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

Output:

01:23

(depending on the current time)

Example 2.44. strtotime string

<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)

Arguments

Table 2.21. Arguments

Name Type Required Description Default
format string no Format String which is taken to format the Date/Time Y-m-d

format.nl2br

Wrapper for PHPs nl2br function.

Arguments

No arguments defined.

format.number

Formats a number with custom precision, decimal point and grouped thousands.

Arguments

Table 2.22. Arguments

Name Type Required Description Default
decimals int no The number of digits after the decimal point 2
decimalSeparator string no The decimal point character .
thousandsSeparator string no The character for grouping the thousand digits ,

format.padding

Formats a string using PHPs str_pad function.

Arguments

Table 2.23. Arguments

Name Type Required Description Default
padLength integer yes Length of the resulting string. If the value of pad_length is negative or less than the length of the input string, no padding takes place.
padString string no The padding string

format.printf

A view helper for formatting values with printf. Either supply an array for

the arguments or a single value.

See http://www.php.net/manual/en/function.sprintf.php

Examples

Example 2.45. Scientific notation

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

Output:

3.625e+8

Example 2.46. Argument swapping

<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!

Example 2.47. Single argument

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

Output:

We love TYPO3

Arguments

Table 2.24. Arguments

Name Type Required Description Default
arguments array yes The arguments for vsprintf

groupedFor

Grouped loop view helper.

Loops through the specified values

Examples

Example 2.48. Simple

<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

Example 2.49. Two dimensional list

<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>

Arguments

Table 2.25. Arguments

Name Type Required Description Default
each array yes The array or \SplObjectStorage to iterated over
as string yes The name of the iteration variable
groupBy string yes Group by this property
groupKey string no The name of the variable to store the current group groupKey

if

This view helper implements an if/else condition.

Arguments

Table 2.26. Arguments

Name Type Required Description Default
condition boolean yes View helper condition

layout

With this tag, you can select a layout to be used..

Example 2.50. Example

<f:layout name="main" />

Arguments

Table 2.27. Arguments

Name Type Required Description Default
name string yes Name of layout to use. If none given, “default” is used.

link.action

A view helper for creating links to actions.

Examples

Example 2.51. Defaults

<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)

Example 2.52. Additional arguments

<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)

Arguments

Table 2.28. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
action string no Target action
arguments array no Arguments Array
controller string no Target controller. If NULL current controllerName is used
package string no Target package. if NULL current package is used
subpackage string no Target subpackage. if NULL current subpackage is used
section string no The anchor to be added to the URI
format string no The requested format, e.g. “.html”
absolute boolean no If set, the URI of the rendered link is absolute
addQueryString boolean no If set, the current query parameters will be kept in the URI
argumentsToBeExcludedFromQueryString array no arguments to be removed from the URI. Only active if $addQueryString = TRUE Array
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element
name string no Specifies the name of an anchor
rel string no Specifies the relationship between the current document and the linked document
rev string no Specifies the relationship between the linked document and the current document
target string no Specifies where to open the linked document

link.email

Email link view helper.

Generates an email link.

Examples

<code title=”basic email link”>

Arguments

Table 2.29. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
email string yes The email address to be turned into a link.

link.external

A view helper for creating links to external targets.

Examples

Example 2.53. Example

<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>

Arguments

Table 2.30. Arguments

Name Type Required Description Default
additionalAttributes array no Additional tag attributes. They will be added directly to the resulting HTML tag.
uri string yes the URI that will be put in the href attribute of the rendered link tag
class string no CSS class(es) for this element
dir string no Text direction for this HTML element. Allowed strings: “ltr” (left to right), “rtl” (right to left)
id string no Unique (in this file) identifier for this HTML element.
lang string no Language for this element. Use short names specified in RFC 1766
style string no Individual CSS styles for this element
title string no Tooltip text of element
accesskey string no Keyboard shortcut to access this element
tabindex integer no Specifies the tab order of this element
name string no Specifies the name of an anchor
rel string no Specifies the relationship between the current document and the linked document
rev string no Specifies the relationship between the linked document and the current document
target string no Specifies where to open the linked document

render

Arguments

Table 2.31. Arguments

Name Type Required Description Default
section string no Name of section to render. If used in a layout, renders a section of the main content file. If used inside a standard template, renders a section of the same file.
partial string no Reference to a partial.
arguments array no Arguments to pass to the partial. Array

section

A Section view helper

Arguments

Table 2.32. Arguments

Name Type Required Description Default
name string yes Name of the section

security.ifAccess

This view helper implements an ifAccess/else condition.

Examples

Example 2.54. Basic usage

<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.

Example 2.55. IfAccess / then / else

<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.

Arguments

Table 2.33. Arguments

Name Type Required Description Default
resource string yes ACL resource

security.ifHasRole

This view helper implements an ifHasRole/else condition.

Examples

Example 2.56. Basic usage

<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.

Example 2.57. IfRole / then / else

<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.

Arguments

Table 2.34. Arguments

Name Type Required Description Default
role string yes The role

then

“THEN” -> only has an effect inside of “IF”. See If-ViewHelper for documentation.

Arguments

No arguments defined.

uri.action

A view helper for creating URIs to actions.

Examples

Example 2.58. Defaults

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

Output:

currentpackage/currentcontroller

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

Example 2.59. Additional arguments

<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)

Arguments

Table 2.35. Arguments

Name Type Required Description Default
action string no Target action
arguments array no Arguments Array
controller string no Target controller. If NULL current controllerName is used
package string no Target package. if NULL current package is used
subpackage string no Target subpackage. if NULL current subpackage is used
section string no The anchor to be added to the URI
format string no The requested format, e.g. “.html”
absolute boolean no If set, an absolute URI is rendered
addQueryString boolean no If set, the current query parameters will be kept in the URI
argumentsToBeExcludedFromQueryString array no arguments to be removed from the URI. Only active if $addQueryString = TRUE Array

uri.email

Email uri view helper.

Currently the specified email is simply prepended by “mailto:” but we might add spam protection.

Examples

<code title=”basic email uri”>

Arguments

Table 2.36. Arguments

Name Type Required Description Default
email string yes The email address to be turned into a mailto uri.

uri.external

A view helper for creating URIs to external targets.

Currently the specified URI is simply passed through.

Examples

Example 2.60. Example

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

Output:

http://www.typo3.org

Arguments

Table 2.37. Arguments

Name Type Required Description Default
uri string yes the target URI

uri.resource

A view helper for creating URIs to resources.

Examples

Example 2.61. Defaults

<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)

Arguments

Table 2.38. Arguments

Name Type Required Description Default
packageKey string no Target package key. If not set, the current package key will be used

ers.

Humanize a camel cased value

Examples

Example 2.62. Example

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

Output:

Camel cased model name

Arguments

Table 2.39. Arguments

Name Type Required Description Default
lowercase boolean no Wether the result should be lowercased

ers.

Pluralize a word

Examples

Example 2.63. Example

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

Output:

foos

Arguments

No arguments defined.

ers.rawValue

Wrapper to pass through values as-is

Examples

Example 2.64. Example

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

Output:

textWith>Add>AndStuff

Arguments

No arguments defined.

ers.uppercaseFirst

Wrapper for PHPs ucfirst function.

Arguments

No arguments defined.


[1] Remember: The semantics between the controller and the view should be the following: The controller says to the view “Please render the blog object I give to you”, and not “Please render the Blog title, and the blog posting 1, …”. That’s why passing objects to the view instead of simple values is highly encouraged.

[2] This is like an XML namespace import, just with a different syntax.

[3] This view helper is already available in the standard library as <f:for>..</f:for>. We still use it as example here, as it is quite simple and shows many possibilities.

[4] Remember that the view helper can receive arbitary objects as parameters!

[5] There are always some religious discussions whether to allow non-standard attributes or not. People being against it argue that it “pollutes” HTML, and makes it not validate anymore. More pragmatic people see some benefits to custom attributes in some contexts: If you use JavaScript to evaluate them, they will be ignored by the rendering engine if JavaScript is switched off, and can enable special behavior when JavaScript is turned on. Thus, they can make it easy to provide degradable interfaces.

(Before bashing Dojo now: Of course you do not need the additional HTML arguments, but they make work with it a lot more comfortable)

发表评论

电子邮件地址不会被公开。 必填项已用*标注