Skip to content

Use fluid components #6432

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Alagts wants to merge 11 commits into
base: main
Choose a base branch
from
Open

Use fluid components #6432

Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
46bfde6
Using Fluid components
Alagts Mar 17, 2026
2a7d25a
Split commit in smaller parts
Alagts Mar 24, 2026
34d61e1
Update branch with new changes from main
Alagts Mar 24, 2026
c7f9ecd
Update Documentation/ApiOverview/Fluid/UsingFluidInTypo3.rst
Alagts Mar 24, 2026
1daa287
Update Documentation/ApiOverview/Fluid/UsingFluidInTypo3.rst
Alagts Mar 24, 2026
160acd9
Update Documentation/ApiOverview/Fluid/UsingFluidInTypo3.rst
Alagts Mar 24, 2026
32de3e2
Update Documentation/ApiOverview/Fluid/UsingFluidInTypo3.rst
Alagts Mar 24, 2026
d660017
Add codesnippets (#6433)
Alagts Mar 24, 2026
b063e36
Add codesnippets for Fluid events (#6435)
Alagts Mar 24, 2026
4af1e10
Outsource ComponentsCollection.php, put Fluid components introduction…
Alagts Mar 24, 2026
53b4984
Resolve conflicts
Alagts Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 234 additions & 0 deletions Documentation/ApiOverview/Fluid/UsingFluidInTypo3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ Here are some examples of how Fluid can be used in TYPO3:
* :php:`TYPO3\CMS\Extbase\Mvc\View\ViewResolverInterface`
* :php:`TYPO3\CMS\Extbase\Mvc\View\GenericViewResolver`

.. contents::
:local:

.. _fluid-syntax-viewhelpers-import-namespaces:

Expand Down Expand Up @@ -142,6 +144,238 @@ The namespace here is 'my'. For further information visit
`ViewHelper namespaces <https://docs.typo3.org/permalink/fluid:viewhelper-namespaces-syntax>`_
in Fluid explained.

.. _using_fluid_components:

Using Fluid components
======================

.. _description_fluid_components:

Description
-----------

With version 4.3 the concept of components was introduced into Fluid.
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this needs a ".. versionadded:: 14.3" instead of a description?

Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is about Fluid, I think it is sufficient to just mention it in the text.


.. _register_fluid_components:

Registering component collections
---------------------------------

In order to use Fluid components register a component collection
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In order to use Fluid components register a component collection
In order to use Fluid components, register a component collection

within the file :file:`Configuration/Fluid/ComponentCollections.php`

.. code-block:: php
:caption: EXT:my_extension/Configuration/Fluid/ComponentCollections.php

<?php
Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we put this into a separate file? This way, the file is automatically formatted.


return [
'MyVendor\\MyExtension\\Components' => [
'templatePaths' => [
10 => 'EXT:my_extension/Resources/Private/Components',
],
],
];

in which you define the path your Fluid components can be found.
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
in which you define the path your Fluid components can be found.
in which you define the path where your Fluid components can be found.

Components in that collections can then be used in any Fluid template.
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Components in that collections can then be used in any Fluid template.
Components in these collections can then be used in any Fluid template.


.. code-block:: html
:caption: EXT:my_extension/Resources/Private/Templates/Template.fluid.html

<html
xmlns:my="http://typo3.org/ns/MyVendor/MyExtension/Components"
data-namespace-typo3-fluid="true"
>

<my:organism.header.navigation />

Note that by default, component collections use a folder structure that
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note that by default, component collections use a folder structure that
Note that, by default, component collections use a folder structure that

requires a separate directory per component.
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
requires a separate directory per component.
requires a separate directory for each component.

That means, for example, imagine you defined a navigation Fluid component.
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
That means, for example, imagine you defined a navigation Fluid component.
That means, for example, if you have defined a navigation Fluid component

Then the file
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Then the file
then the file

:file:`EXT:my_extension/Resources/Private/Components/Organism/Header/Navigation/Navigation.fluid.html`
should be stored in path `my_extension/Resources/Private/Components/Organism/Header/Navigation`.

All arguments that are passed to a component need to be defined with
:html:`<f:argument>` in the component template, for example
:file:`Navigation.fluid.html`.
Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mention "Navigation.fluid.html", but is there an example available where someone can see the <f:argument>s?


It is possible to adjust these configurations per collection:

* using `templateNamePattern` allows you to use a different folder structure,
available variables are `{path}` and `{name}`. For example,
with :html:`<my:organism.header.navigation>`, `{path}` would be
`Organism/Header` and `{name}` would be `Navigation`.
* setting `additionalArgumentsAllowed` to `true` allows passing undefined arguments
to components.

Here is an example where these configurations are used.

.. code-block:: php
:caption: EXT:my_extension/Configuration/Fluid/ComponentCollections.php

<?php

return [
Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use a full example so it is clear where to put this snippet.

'MyVendor\\MyExtension\\Components' => [
'templatePaths' => [
10 => 'EXT:my_extension/Resources/Private/Components',
],
'templateNamePattern' => '{path}/{name}',
'additionalArgumentsAllowed' => true,
],
];

Using this example :html:`<my:organism.header.navigation />` would point to
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Using this example :html:`<my:organism.header.navigation />` would point to
Using this example, :html:`<my:organism.header.navigation />` would point to

:file:`EXT:my_extension/Resources/Private/Components/Organism/Header/Navigation.fluid.html`
(note the missing :file:`Navigation` folder).

It is possible to influence certain aspects of Fluid components using PSR-14 events,
see `PSR-14 events for Fluid components <https://docs.typo3.org/permalink/changelog:feature-108508-1765987847>`_.

.. _creating_fluid_components:

Creating components
-------------------

The typical look of a component is like a normal Fluid template, except
that it defines all of its arguments with the
`Argument ViewHelper <f:argument> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-argument>`_.
The `Slot ViewHelper <f:slot> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-slot>`_
can be used to receive other HTML content. With the Slot ViewHelper it is possible to nest components.
Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please link "Slot ViewHelper" to the Fluid VH docs.

Copy link
Copy Markdown
Contributor Author

@Alagts Alagts Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just before this line it is linked. :)


Example: How you could define a Fluid component
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Example: How you could define a Fluid component
Here is an example of how you could define a Fluid component:


.. code-block:: html
:caption: EXT:my_extension/Resources/Private/Components/Molecule/TeaserCard/TeaserCard.fluid.html

<html
xmlns:my="http://typo3.org/ns/MyVendor/MyExtension/Components"
data-namespace-typo3-fluid="true"
>

<f:argument name="title" type="string" />
<f:argument name="link" type="string" />
<f:argument name="icon" type="string" optional="{true}" />

<a href="{link}" class="teaserCard">
<f:if condition="{icon}">
<my:atom.icon identifier="{icon}">
</f:if>
<div class="teaserCard__title">{title}</div>
<div class="teaserCard__content"><f:slot /></div>
</a>

The example also demonstrates that components can (and should) use other components, in this
case :html:`<my:atom.icon>`.
Depending on the use case, it might also make sense to pass the output of one component
to another component via a slot:

.. code-block:: html

<html
xmlns:my="http://typo3.org/ns/MyVendor/MyExtension/Components"
data-namespace-typo3-fluid="true"
>

<my:molecule.teaserCard
title="TYPO3"
link="https://typo3.org/"
icon="typo3"
>
<my:atom.text>{content}</my:atom.text>
</my:molecule.teaserCard>

You can learn more about components in
`Defining Components <https://docs.typo3.org/permalink/fluid:components-definition>`_. Note
that this is part of the documentation of Fluid Standalone, which means that it doesn't mention
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
that this is part of the documentation of Fluid Standalone, which means that it doesn't mention
that this is part of the Fluid Standalone documentation, which means that it doesn't mention

TYPO3 specifics.

.. _history_fluid_components:

History of Fluid components
---------------------------

In TYPO3 v13 it is possible to use components in TYPO3 projects by creating a custom
:php:`ComponentCollection` class that essentially connects a folder of template files
to a Fluid ViewHelper namespace. Using that class it is also possible to use an
alternative folder structure for a component collection and to allow passing
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
alternative folder structure for a component collection and to allow passing
alternative folder structure for a component collection and to allow

arbitrary arguments to components within that collection.
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
arbitrary arguments to components within that collection.
arbitrary arguments to be passed to components in that collection.


.. _migration_co-existence_fluid_components:

Migration and co-existence with class-based collections
-------------------------------------------------------

Since TYPO3 v14 you should use the configuration-based component collections over
Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest to first create a PR for v13 and main. When this is merged/backported (and all work done for v13), then the v14 part should be worked on which is then merged only to main.

Otherwise you end up with documentation for v14 in v13 docs - which is not really ideal.

Copy link
Copy Markdown
Contributor

@s2b s2b Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd argue that Fluid Components shouldn't really be documented for TYPO3 v13. The fact that they could be used in v13 was kind of a hack, now official support is added with v14, which is when this should be documented in the TYPO3 documentation.

Nevertheless, if you come from v13, there should be a place that shows how to migrate the old implementation to the new one.

Copy link
Copy Markdown
Contributor

@brotkrueml brotkrueml Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, fine for me. As a "Releases" line is lacking, it was not obvious for which branches the PR is meant.

the class-based. A configuration-based component collection is a collection defined
by the configuration file :file:`ComponentCollections.php`. In contrast to that, a
class-based component required custom PHP code in TYPO3 v13, see
`Fluid components in Fluid explained <https://docs.typo3.org/permalink/fluid:components-setup>`_.
Most use cases can easily be migrated to the configuration-based approach, since
they usually just consist of boilerplate code around the configuration options.

In fact, you can use both component collection types side by side. For more
advanced use cases, it might still be best to ship a custom class to define
a component collection. Since the configuration-based approach is not available in TYPO3 v13,
it is possible to ship both variants to provide backwards-compatibility:
if a specific component collection is
defined both via class and via configuration, in TYPO3 v13 the class will be used,
Copy link
Copy Markdown
Contributor

@sarahmccarthy123 sarahmccarthy123 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
defined both via class and via configuration, in TYPO3 v13 the class will be used,
defined both by class and by configuration, in TYPO3 v13 the class will be used,

while in TYPO3 v14 the configuration will be used and the class will be ignored completely.

.. _extending_component-collections_fluid_components:

Extending component collections from other extensions
-----------------------------------------------------

It is possible to extend the configuration of other extensions using the
introduced configuration file. This allows integrators to merge their own set of
components into an existing component collection:

.. code-block:: php
:caption: EXT:vendor_extension/Configuration/Fluid/ComponentCollections.php

<?php

return [
'SomeVendor\\VendorExtension\\Components' => [
'templatePaths' => [
10 => 'EXT:vendor_extension/Resources/Private/Components',
],
],
];

.. code-block:: php
:caption: EXT:my_extension/Configuration/Fluid/ComponentCollections.php

<?php

return [
'SomeVendor\\VendorExtension\\Components' => [
'templatePaths' => [
1765990741 => 'EXT:my_extension/Resources/Private/Extensions/VendorExtension/Components',
],
],
];

For template paths, the familiar rule applies: they will be sorted by their
keys and will be processed in reverse order. In this example, if `my_extension`
defines a component that already exists in `vendor_extension`, it will override
the original component in `vendor_extension`.

.. _psr_14_events_fluid_components:

PSR-14 events for Fluid components
----------------------------------

There are three new PSR-14 events to influence the processing and rendering of
Fluid components that can be registered using the new configuration file.
(see `Feature: #108508 - Fluid components integration <https://docs.typo3.org/permalink/changelog:feature-108508-1765987901>`_).

* ModifyComponentDefinitionEvent
* ProvideStaticVariablesToComponentEvent
* RenderComponentEvent

.. _generic-view-factory:

Expand Down