24 Tips & Tricks for Fluid

 <!-- Assigning variables //-->
1) <f:variable name="myvar" value="Hardcoded value"/>
2) <f:variable name="myvar">Larger expressions or static code</f:variable>
3) {f:variable(name: 'myvar', value: 'Hardcoded value')}
4) {my:expensiveViewHelper() -> f:variable(name: 'myvar')}

Then makes expression to use in f:render and others:

<f:render partial="MyPartial" arguments="{myvar: myvar}"/>

Rather than having to do, for example:

<f:render partial="MyPartial" arguments="{myvar: '{my:expensiveViewHelper()}'}" />

Which is *particularly* useful to avoid escaping inline syntax quotes!

<!-- Simple math -->
<f:variable name="floatPercent" value="0.25" />
Percent done: {floatPercent * 100}%

<f:variable name="total" value="12" />
<f:variable name="done" value="3" />
Progress: {total - done} remaining.

<!-- Parsing enabled modifier -->
{parsing off}

This is a {{ mustache }}, <custom:xml>xml</custom:xml>
or other template which uses syntax that could be
confused with Fluid syntax. So we use {parsing off}
to completely disable Fluid in this particular file.

The template will not get parsed as Fluid even
when you render it with <f:render />. You can use
this to "include" a piece of such code into your
main Fluid template. 

<!-- Default values when partial/section not found -->
<f:render partial="Missing" optional="1" default="Partial 1 not found" />

<f:render partial="AlsoMissing" optional="1">
  Partial 2 not found
</f:render>

<!-- Outputs: -->
Partial 1 not found Partial 2 not found

<!-- Recursive variable resolving -->
<f:variable name="array" value="{0: 'foo', 1: 'bar'}" />
<f:variable name="index" value="1" />
Variable "index" contains the array position we need.
Dynamic array index #{index}: {array.{index}} <!-- bar -->

<f:variable name="typeOne" value="This is type 1" />
<f:variable name="typeTwo" value="This is type 2" />
<f:variable name="selectedType" value="Two" />
Variable "selectedType" is a string that's part of a variable name.
Dynamic named variable: {type{selectedType}} <!-- This is type 2 -->

<!-- Ternary condition -->
<f:variable name="variableToCheck" value="0" />
<f:variable name="option1" value="Option one" />
<f:variable name="option2" value="Option two" />
One of two options: {variableToCheck ? option1 : option2}
Fallback if variable not set: {option1 ? option1 : option2}

<!-- Outputs: -->
One of two options: Option two
Fallback if variable not set: Option one

<!-- Invalid: -->
{variableToCheck ? 'some text' : 'other text'}

<!-- Removing meaningless whitespace -->
<f:spaceless>
  <div>
    <section>
      <p>
        Whitespace preserved inside tags
      </p>
      <p>But gets removed between tags</p>
    </section>
  </div>
</f:spaceless>

<!-- Outputs: -->
<div><section><p>
  Whitespace preserved inside tags
</p><p>But gets removed between tags</p></section></div>

<!-- Disabling HTML escaping for an entire file -->
{escaping off}

Any variables you render will not need to use f:format.raw
even if they contain special HTML entities. Useful when
you render formats other than HTML; or when you completely
trust (read: escaped before assigning to view) all your
variables that get output.

Use with care - caveat emptor!

<!-- Rendering sections or partials with dynamic names -->
A common use case is to switch the rendering of an object
based on the type the object has. Fluid supports using
f:render to render a section or partial where the name,
or part of the name, is taken from a variable or other
ViewHelper call. Useful when combined with a default
value in f:render to output when for example no type is
selected yet in the object.

<f:variable name="myType" value="Text" />
<!-- Switching {myType} to Image changes rendering -->

<f:section name="RenderAsText">
  Text version of object
</f:section>

<f:section name="RenderAsImage">
  Image version of object
</f:section>
<!-- Rendering section with partially dynamic name -->

<f:render section="RenderAs{myType}" optional="1" /> 

// Globally registered fluid namespace
$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['my'] = ['MyVendor\\MyExtension\\ViewHelpers'];
// Makes "my" a namespace in Fluid, e.g. "<my:foobar>" resolves
// to class MyVendor\MyExtension\ViewHelpers\FoobarViewHelper 

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['f'] = [
    'TYPO3Fluid\\Fluid\\ViewHelpers',
    'TYPO3\\CMS\\Fluid\\ViewHelpers'
];

<!-- Giving variables default values if they are NULL -->
{class -> f:or(alternative: 'my-default') -> f:variable(name: 'class')}
{label -> f:or(alternative: 'No name') -> f:variable(name: 'label')}
{body -> f:or(alternative: 'Body not set') -> f:variable(name: 'body')}

<!-- Purpose: guarantee a value is filled for mandatory output -->
<div class="{class}">
  <h4>{label}</h4>
  <f:format.html>{body}</f:format.html>
</div>

<!--
Works well when your fields *must* always be output but don't necessarily
have a value, e.g. are TCA fields with no requirement for a value.
--> 

<!-- Registering multiple namespaces with same alias -->
{namespace f=Vendor\MyFluidOverrides\ViewHelpers}
{namespace my=Vendor\MyExtensionOne\ViewHelpers}
{namespace my=Vendor\MyExtensionTwo\ViewHelpers}

Namespace "f" is now overlaid with ViewHelpers from the
"Vendor\MyFluidOverrides\ViewHelpers" PHP namespace and
any class you create there (e.g. "VariableViewHelper")
will override the corresponding class from Fluid.

Namespace "my" is created with two namespace lookups,
first in "Vendor\MyExtensionTwo\ViewHelpers" and then
in "Vendor\MyExtensionOne\ViewHelpers" (last imported
gets checked first).

Use this to construct different versions of ViewHelpers
when you need to customise the behavior of them for a
given project. Or merge namespaces for convenience
when you use ViewHelpers from multiple packages.

<!-- Using f:render to make "blocks" of output -->
Rendering into a variable and then using that variable
can make the template more readable. This example is
VERY small; the bigger and more costly the rendering is,
the more sense it makes to use this trick.

<f:section name="Icon">
  <span class="icon-{icon}"></span>
</f:section>

{f:render(section: 'Icon', arguments: {icon: 'twitter'}) -> f:variable(name: 'twitterIcon')}
{f:render(section: 'Icon', arguments: {icon: 'facebook'}) -> f:variable(name: 'facebookIcon')}

And use them as frequently as we want:

<div class="share">
  Share here!
  {twitterIcon -> f:format.raw()}
  {facebookIcon -> f:format.raw()}
</div>

<div class="also-share">
  Or here!
  {twitterIcon -> f:format.raw()}
  {facebookIcon -> f:format.raw()}
</div>

<!-- Else-if structure -->
Fluid can render "if" and "else" and we all know how that
works - but Fluid can also render "else-if" type structures:

<f:if condition="{var} > 100">
  <f:then> Overflow! </f:then>
  <f:else if="{var} > 90"> Danger! </f:else>
  <f:else if="{var} > 50"> Careful now. </f:else>
  <f:else> All good! </f:else>
</f:if>

<!-- Passing rendered Fluid to a partial as variable -->
With "contentAs" on f:render you can make it render the tag
content and pass this to the partial as a variable you name.

This enables you to use f:render and partials to wrap output
in different ways. Consider the following example:

<f:render partial="MySpecialWrap" contentAs="content">
  <div class="wrappable-content">
    <h4>This content can be wrapped</h4>
    <!-- Fluid can be used without restrictions here -->
  </div>
</f:render>

And the following template source in the "MySpecialWrap"
partial template:

<!-- In partial MySpecialWrap.html -->
<div class="outerwrap wrap-foobar">
  <section>
    {content -> f:format.raw()}
  </section>
</div>

And remember the previous f:render tips:

* The name of the partial can be dynamic, so you can make
  this apply a dynamic type of wrapping.
* This also works with sections, of course.
* You an also combine this with "default" argument (but
  obviously you cannot use the tag content as default)

<!-- "Renderable" interface for objects -->
Normally, you build template output using variables that
you assign to the template and then output. But there is
an alternative approach, by using a delegate object to
render output. A Renderable is a cross between a ViewHelper
and template variable: but rather than parse the template
and detect a ViewHelper class to initialize and render,
you control the prepared object instance that gets rendered
and assign that instance to the template.

use \TYPO3Fluid\Fluid\Core\Rendering\AbstractRenderable;
use \TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;

class MyRenderable extends AbstractRenderable
{
  public function render(RenderingContextInterface $renderingContext)
  {
    // Any PHP execution you want. The RenderingContext
    // will be the exact one that's active when you
    // render the renderable (and contains variables etc.)
    return 'My special rendering';
  }
}
  
// then assign a view variable with an instance of MyRenderable.

 <f:render renderable="{renderable}" /> 

<!-- The "data" attribute on TagBasedViewHelpers -->
All ViewHelpers which use the AbstractTagBasedViewHelper
parent class, or internally use the TagBuilder from Fluid,
have the option of supporting arbitrary "data-*" attributes
in two ways:

1) <v:h data-foobar="baz" data-biz="biz">content</v:h>
2) <v:h data="{foobar: 'baz', biz: 'biz'}">content</v:h>

Assuming "v:h" outputs a "div" tag, both examples output:

<div data-foobar="baz" data-biz="biz">content</div>

The two methods can also be combined, but the more specific
"data-foobar" naming will override the corresponding value
if it is also passed in the "data" array.

The main idea is that no registration is required for each
"data-*" argument you pass, making it a lot easier for a
frontend developer to add new attributes without knowing
about the complex inline Fluid syntax and escaping that
would be necessary if passing all "data-*" attributes in
the "data" array. 

// Using a JSON file as fallback values for a template
$existingVariables = $view->getRenderingContext()->getVariableProvider();
$jsonVariables = new \TYPO3Fluid\Fluid\Core\Variables\JSONVariableProvider();

// Supported JSON source types:
// 1) Local JSON file path
// 2) Remote JSON file path
// 3) JSON string source

$jsonVariables->setSource($jsonFilePathOrJsonSource);
$newVariables = new \TYPO3Fluid\Fluid\Core\Variables\ChainedVariableProvider(
  [
    $jsonVariables, $existingVariables
  ]
);
$view->getRenderingContext()->setVariableProvider($newVariables);

<!-- Layouts: default and dynamic Layout names -->
First, f:layout has a little known default value for the
layout name. When your layout is named "Default" you can
omit the "name" argument:

<f:layout />

Second, the name of the layout can come from a variable,
but needs special care to ensure that a valid layout is
always selected, even if the variable has no value.

Don't:

<f:layout name="{layout}" />

But do:

<f:layout name="Custom{layout}" />

...and make sure you have a fallback "Custom" layout, in
addition to "CustomFoo", "CustomBar" or whichever values
the {layout} variable may have. In other words: treat
your dynamic layout name as a suffix for a filename.

<!-- Namespace imports and ignored namespaces -->
The following are the ways you can import Fluid namespaces
in template files and how they work:

1)
<html xmlns:f="typo3.org/ns/TYPO3/CMS/F…">
  This approach means you can have tag-completion via XSD.
  This particular notation *PRESERVES* the "html" tag.
</html>

2)
<html xmlns:f="typo3.org/ns/TYPO3/CMS/F…" data-namespace-typo3-fluid="true">
  This approach is the same as above, but *REMOVES* the "html" tag due to the
  "data-namespace-typo3-fluid" mark.
</html>

3)
{namespace foo=MyVendor\MyPackage\ViewHelpers}
This approach registers a single namespace. As with all curly-
braces based imports, the marker gets removed before output.

4)
{namespace foo}
This approach completely ignores any <foo:vh /> tags and will
allow them to be output including the namespace, without them
being seen as Fluid code. The particular notation here ignores
a single namespace.

5)
{namespace fo*}
This final approach ignores any tags like the one above, but
will match any namespace that starts with "fo" - e.g. will
match both "foo" and "fox".

<!-- Reducing the need to escape quotes -->
In Fluid, when you nest ViewHelper expressions, you are required
to escape any nested quotes. This can quickly become difficult:

<f:render partial="Foobar" arguments="{
  label: '{f:if(condition: lll, then:
  \'{f:translate(key: \\'mylabel\\')}\',
  else: \'foobar\')}
}" />

Since the number of escapes must always increase by one for every
time you use a new pair of quotes, it can quickly become too
difficult to manage.

There is however a way to avoid it: by assigning intermediate
variables and whenever possible, passing content as child node
instead of using a named argument.

{f:translate(key: 'mylabel')
  -> f:if(condition: lll, else: 'foobar')
  -> f:variable(name: 'label')}
<f:render partial="Foobar" arguments="{label: label}" />

Three tricks are used to reduce the need to use quotes:

1. Rather than using "then" on f:if to pass a translated label,
   we pass it as the only child node to f:if - same meaning.
2. The arguments that do require quoting, we keep on the same
   "escaping level" so they only require a single quote.
3. A variable is assigned so we can pass the result to other
   ViewHelpers like f:render, without using any quotes at all.

You can combine this strategy with all the preceding tips about
using f:render, inline syntax, f:or and much more.

Happy coding and merry Christmas!