Fluid best practice

Templating manual

Edit this chapter on Github Jump to...

1.6 Fluid best practices

Naming Conventions

In Fluid, you must always follow the UpperCamelCase naming convention for files - e.g. MyTemplateFile.html. This goes for Partials and Layouts as well. Fluid itself supports multiple formats, but Fluid Powered TYPO3 currently only supports one format: .html.

Your Partials and Layouts can also be placed in subfolders and referred to using a subfolder path:

<!-- Using EXT:myextensionkey/Resources/Private/Layouts/Subfolder/MyLayout.html -->
<f:layout name="Subfolder/MyLayout" />

<!-- Rendering EXT:myextensionkey/Resources/Private/Partials/Subfolder/MyPartial.html -->
<f:render partial="Subfolder/MyPartial" />

The UpperCamelCase format should be used for:

  • Every PHP class name in your provider extension
  • Every template - Layouts, Partials and Templates
  • Every f:section you use in every template

The lowerCamelCase format (without underscores) should be used for:

  • Every argument name on every ViewHelper
  • Every variable you assign to your templates
  • Every field name you create using Flux (dotted.path.actualName is okay too)
  • Every function you create in every PHP class and every argument in those functions
  • Every variable you use in PHP
  • Every language label name (dotted.path.actualName is okay too)

The lowercase_underscored format (no uppercase letters) is only used for:

  • References to your extension key (which is different from the extension name in Fluid and Extbase) _excluding references to the TypoScript location for your extension)
  • Legacy language labels (current format is as mentioned above, the lowerCamelCase format
Note about underscores in extension keys: An extension called my_extension is referred to using MyExtension when the format is requested as extensionName, as my_extension when the requested format is extensionKey and finally, Vendor.MyExtension when the format is (for example) combinedExtensionKey (but is also often possible to use when the requested format is extensionName and there is no specific vendorName argument). Because of this fairly esoteric behavior the absolute recommendation is to **avoid underscores in your extension key. Unless, of course, you know what you are doing.

Fluid Performance Concerns

Fluid works by parsing your templates into PHP object structures. Each ViewHelper you use inside another ViewHelper increases the nesting level (e.g. an f:link.page inside an f:if renders the f:link.page from inside the class which handles the f:if tag). Limiting the maximum nesting level means fewer functions will be called, and limiting the number of ViewHelper tags you use, naturally limits the time Fluid will need in order to parse your templates.

As a rule of thumb you should consider splitting your template file's contents into one or more Partial templates. Since Partial templates are also cached as PHP, offloading some rendering to Partials can be very beneficial. Especially if this rendering is performed from more than one place.

Note: even Flux forms and form fields can be put into Partial templates and even divided into f:sections inside this Partial template. Simply f:render the Partial (and section) from within your flux:form tag and Fluid will call the correct PHP code to create the correct form fields and insert them into the correct container element (Sheet, Object, etc).

In order to speed up rendering Fluid will (attempt to) cache some selected ViewHelpers as pure PHP code - but if Fluid encounters a so-called uncompilable ViewHelper in a template, the template cannot be converted to pure PHP code. You can use the extension called builder to detect if this is happening - or you can investigate the ViewHelper classes you use and check for occurrences of the ChildNodeAccessInterface interface in a class which has no compile() method. Unfortunately Fluid has no debugging flag which can be set to warn about such ViewHelpers, so it is generally recommended to run builder's checks once in a while (and particularly before you deploy the template). Avoiding uncompilable ViewHelpers (or if this is impossible, placing them in a separate Partial template with a very limited amount of template code) is key to obtaining good performance when rendering Fluid templates.

Once cached into the page/content cache, Fluid has no impact on your pages' display speed. The impact is only when building the page - and if your Fluid templates are properly compilable, it's this page building step which is greatly improved.

Obviously your focus on performance should be in the page templates first, content templates second. Page templates which compile to pure PHP are much more efficient because once one page is rendered, all pages after this will render using the pure PHP code and will completely skip the template parsing step.

Variable Performance Concerns

Fluid templates make wide use of variables, the value of which you can define from outside the template. While variables themselves do not add much in terms of CPU and memory usage, they do add to the complexity of your templates and increase the likelyhood of colissions which must be solved in order for the template to render. You can limit the number of variables and decrease colission risk by following a few simple suggestions:

  • Limit your use of v:variable.set - but use it more often if you find yourself using long chains of Fluid tags to manipulate a certain variable. Avoiding long duplicated Fluid chains limits the number of methods Fluid must call
  • Be conservative about passing the special {_all} keyword variable when rendering sections and Partials. When you do, every variable is passed which makes it both harder to know which variables are available in the Partial or section - but also makes Fluid create a copy of the entire arguments array. This is always a trade-off: having to pass too many variables means Fluid needs to parse many additional template nodes so sometimes, {_all} can be more efficient - but less transparent

Don't Fear Custom ViewHelpers

Sometimes the ViewHelpers provided in Fluid and VHS are not enough to get you where you need to be - and sometimes you need to use so many different ViewHelpers that performance suffers as a consequence. If you encounter such a case it's always a good idea to ask if your use case makes sense as an addition to VHS - but if it is not, you have a great option right at hand: making and using a custom ViewHelper class.

Since Fluid Powered TYPO3 requires you to use an extension for your template files you already have the perfect place to create custom ViewHelpers. You can use virtually any ViewHelper in VHS or Fluid (note: there are four main types, in order of most frequent occurrence they are standard, tag-based, condition and finally widget types) as a starting point. Include your own namespace same as you include the VHS namespace - and you've got a perfect way to do more complex PHP operations without having to create a custom controller class.

Continue: Chapter 1.7: Portable code.

Jump to...