1.3 Template file usage

It should be pretty clear that we use Extbase's conventions to place configuration and template folders and files and that your provider extension is simply a standard TYPO3 extension with some predefined file structure. The way you use each folder normally depends on which type of Provider Extension you are creating - and the feature-specific guides always start by explaining which folders and files are involved.

Your ext_localconf.php and ext_tables.php files will contain the various calls to Flux to register which types of Flux templates your Provider Extension uses - along with any other configuration you might need; custom TCA fields for tt_content fx. The Resources/Private folder contains a template structure and the language file - and the templates are divided into subfolders by name of the controller which will render them (e.g. in fluidpages the controller is named PageController which means the folder name is Page, in fluidcontent the controller name is Content and so on). Layouts and Partials are supported just like normal. And finally, the Configuration directory contains the TypoScript that your extension makes available for integrators to select and use in TYPO3 when your Provider Extension is installed.

What must the template files contain?

The actual contents of template files depends on which feature they should be used with - but there are a few shared rules which you can read all about in the Templates concept chapter of this documentation. Following the standard rules always results in a working, selectable (yet very minimal) template - what the template should contain in addition to the standard format is up to each specific feature and is documented by each feature.

The only files which are required to contain the standard format, are the files located under Templates - in other words: your Layouts and Partials can contain any content you want, but Templates must contain Flux-specific information.

How is a Flux template different from plain Fluid?

A template file which can be used by Flux is exactly the same as a normal fluid template - but with some added requirements:

1. The namespace {namespace flux=FluidTYPO3\Flux\ViewHelpers} must be present.
2. There must be a Configuration section created using f:section.

Inside the Configuration section (or whichever name you chose, in case you chose not to follow conventions) you should place a flux:form tag containing at least an id attribute which should have a lowerCamelCase value, for example specialImage.

There is an optional section you can add when your Flux template is going to be used with the tt_content table - the section called Preview (again, added using f:section) can contain HTML output that is displayed in the page module in TYPO3 when you view that particular record. This works automatically for Flux-enabled plugins (which includes but is not limited to elements for use in fluidcontent).

The final convention - which you should follow for transparency but which can be ignored when necessary, is to name the section which contains the actual output rendering for the frontend, Main - this section gets rendered from the Layout you use, which means you can of course choose a different name if that makes sense. Using the name Main simply means other people will immediately know the purpose of that section.

An extremely minimal template example (example: fluidcontent element template):

{namespace flux=FluidTYPO3\Flux\ViewHelpers}
<f:layout name="Content" />
<f:section name="Configuration">
    <flux:form id="myContentElement" />
</f:section>
<f:section name="Main">
    My content element
</f:section>

As you can see, this minimal example fulfills only the two main requirements above and uses name conventions for the Layout which we describe in the next chapter. If added to a fluidcontent template collection, this template would result in one new content element type named "myContentElement" which has no extra form fields, no special icon, no human-readable label and when rendered, displays a simple "My content element" text without any HTML container element.

Alternative to templates

Note that there is an alternative to placing your form and fields inside the template. When you use a custom Provider class you can have this class return PHP objects directly from the getForm and getGrid methods. Your Provider will have inherited those two methods from Flux's AbstractProvider class - and in the code inherited from Flux, your Provider will by default look into the template file for a Form and Grid instance. When you override either of these methods, reading the Form and Grid respectively, does not have to require reading a template file.

What this means is that if you return native PHP objects from a Provider for both the Form and Grid instances, your template file itself no longer is required to contain a Configuration section and any flux:form definition. Your Provider can even return a raw HTML preview - which when done, lets you skip the Preview section as well. Of course, Previews only apply to tt_content records as already mentioned.

To learn more about your options in this area - when and how to create cutom Provider classes - you can study our Provider class chapters.

Continue: Chapter 1.4: Configuration Usage.