In Fluid templates only values, assigned by the extbase controller, are available. There are cases, in which these values are not sufficient and other data is needed. The “missing” data can be provided through data processors.
In the first part of this this post I will show how to create and use a data processor. Ready to use data processors and real life examples are the topic at the end.
Values usable in fluid templates
In order to get an overview over all available values in a fluid template, you can insert a <f:debug>{_all}</f:debug>
statement anywhere in the template and they will be shown at the beginning of the page. OK, you probably know that, but I wanted to make that sure.
But there might be some more data, you want to use in in the template. This is where data processors will help you. Data processors provide additional values to the fluid template.
How to use data processors
There are three steps, you need to take, in order to use a custom data processor in your fluid template
1) Register the data processor in the fluid template
In a TypoScript definition of a FLUIDTEMPLATE, you must register the data processor in the section dataProcessing
. This section takes a numeric TypoScript array. The value of an element is the class name of the data processor class.
The following example makes is more clear:
page.10 = FLUIDTEMPLATE page.10 { file = path/to/your/templatefile.html dataProcessing { 10 = Name\Of\Your\Dataprocessor 10 { as = variableNameInTheTemplate } } }
The key as
in section 10
defines the key under that the data will be available in the template. All other values of the array will be passed to the class as the processor configuration.
2) Create a class implementing an interface
In the second step you must create a class in the directory Classes/DataProcessing
of your extension. The class must implement the interface DataProcessorInterface
. The interface only contains one function process
. You need to make sure to return the processed data at the end.
A minimalistic implementation might look like this:
<?php namespace MyVendorName\MyExtension\DataProcessing; use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer; use TYPO3\CMS\Frontend\ContentObject\DataProcessorInterface; class MyProcessor implements DataProcessorInterface { public function process( ContentObjectRenderer $cObj, array $contentObjectConfiguration, array $processorConfiguration, array $processedData ) { $processedData['data']['myNewField'] = 'myValue'; return $processedData; } }
Within that function you can do whatever you want. But be careful! If you need many data processors to fetch data from various data sources to make your website work, you should think about the whole architecture of your extension and templating.
3) Make the class known to class loading
In the last step you must make sure, that the class is also known to the class loading mechanism of TYPO3. There are two files, where you should add this information: ext_emconf.php
and composer.json
.
In the ext_emconf.php
you must add these lines:
'autoload' => [ 'psr-4' => [ 'MyVendorName\\MyExtension\\' => 'Classes' ], ],
If you already have a composer.json
file, you probably do not need to add the following lines:
"autoload": { "psr-4": { "MyVendorName\\MyExtension\\": "Classes" } },
This is only necessary, if your data processor should also be used in composer based installations.
Need some ideas, what to do in a dataprocessor?
Ready to use processors and examples
Here are some ready to use data processors from the core and a very useful example from the bootstrap package.
CommaSeparatedValueProcessor (TYPO3 core)
The CommaSeparatedValueProcessor takes an already existing field of the fluid values, splits it into an array depending on the configuration and returns the data as an array.
10 = TYPO3\CMS\Frontend\ContentObject\DataProcessing\CommaSeparatedValueProcessor 10 { if.isTrue.field = bodytext fieldName = bodytext fieldDelimiter = | fieldEnclosure = maximumColumns = 2 as = table }
The usecase of this example is, when your editors use the content element “Table” and you want to apply a sophisticated rendering depending on the settings of “Layout” and “Frame class”.
DatabaseQueryProcessor (TYPO3 core)
The DatabaseQueryProcessor can fetch any record from the database. It uses the same syntax like TypoScript in the .select statement.
10 = TYPO3\CMS\Frontend\DataProcessing\DatabaseQueryProcessor 10 { table = tt_address pidInList = 123 where = company="Acme" AND first_name="Ralph" as = addresses dataProcessing { 10 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor 10 { references.fieldName = image } } }
The result is an array of addresses
, over which you can iterate in your template. Another interesting thing, you can see here, is, that it is possible to nest the data processors, to get more information depending on the result of a field provided by the data processor.
FilesProcessor (TYPO3 core)
The nested processor from the above example is the files processor. This data processor is used to get the relations to sys_file
records like image data. You can use it also to fetch files directly via their uid.
MenuProcessor (TYPO3 core)
This processor uses the HMENU to create an array that contains a representation of a menu. As options, you can use everything what’s also possible within a classic HEMNU content element.
10 = TYPO3\CMS\Frontend\DataProcessing\MenuProcessor 10 { special = list special.value.field = pages levels = 7 as = menu expandAll = 1 includeSpacer = 1 titleField = nav_title // title dataProcessing { 10 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor 10 { references.fieldName = media } } }
If you are interested in real life examples, you can have a look at the bootstrap package. These show very good how the MenuProcessor works.
FlexFormProcessor (Bootstrap package)
Last but not least, there is a FlexFormProcessor in the bootstrap package. This processor delivers all flexform content from the current content element. This is very handy for example, if you use flexforms in your custom content elements. Daniel Goerz wrote a good tutorial about creating custom content elements on his blog.
Conclusion
Data processors are a great way to enrich the data, which are available in fluid templates. Some data processors are already provided with the TYPO3 core. Others are provided by the bootstrap package. You can use these, when you have the bootstrap package installed or take them as a template for your own implementations.
Credits
I want to thank my supporters, who make this blog post possible. This week there is no new bronze sponsor to mention here. But every euro is valuable to me, so I would like to thank Ralph Merz (@merzilla) for his commitment.
If you also appreciate my blog and want to support me, you can say “Thank You!”. Find out the possibilities here:
I found the blog post image on pixabay. It was published by RemazteredStudio under the CC0 Creative Commons License. It was modified by myself using pablo on buffer.