[FEATURE] Named Slots (#1118)

This patch enables Fluid's components to accept multiple slots. Each
slot is identified by a `name` argument. The corresponding
`<f:fragment>` ViewHelper can then be used to fill the slots of a
component.

The available slots of a component are now also exposed properly
via the `ComponentDefinition` DTO. Unfortunately, the `TemplateParser`
fails to propagate available slots of the current templates consistently to
the `ParsingState`, which currently leads to ugly state merging within the
parser. Hopefully, this issue can be addressed in the future to remove this
workaround, which has been documented in the code.

For this first implementation, we limit the usage if the new
`<f:fragment>` ViewHelper to the context of components. However, we
might expand this ViewHelper to other areas in Fluid, such as a way to
partially extend/overwrite templates.

Author: s2b

Documentation/ViewHelpers/Fluid.json

@@ -0,0 +1,21 @@
+..  This reStructured text file has been automatically generated, do not change.
+..  Source: https://github.com/TYPO3/Fluid/blob/main/src/ViewHelpers/FragmentViewHelper.php
+
+:edit-on-github-link: https://github.com/TYPO3/Fluid/edit/main/src/ViewHelpers/FragmentViewHelper.php
+:navigation-title: fragment
+
+..  include:: /Includes.rst.txt
+
+..  _typo3fluid-fluid-fragment:
+
+==================================
+Fragment ViewHelper `<f:fragment>`
+==================================
+
+.. ..  note::
+..     This reference is part of the documentation of Fluid Standalone.
+..     If you are working with Fluid in TYPO3 CMS, please refer to
+..     :doc:`TYPO3's ViewHelper reference <t3viewhelper:Global/Fragment>` instead.
+
+..  typo3:viewhelper:: fragment
+    :source: ../Fluid.json

Documentation/ViewHelpers/Fluid/Fragment.rst

@@ -39,6 +39,11 @@ public function getArgumentDefinitions(): array
         return [];
     }
 
+    public function getAvailableSlots(): array
+    {
+        return [];
+    }
+
     /**
      * Render the parsed template with rendering context
      *

src/Core/Compiler/AbstractCompiledTemplate.php

@@ -189,12 +189,14 @@ public function store(string $identifier, ParsingState $parsingState): ?string
             '    }' . chr(10) .
             '    %s' . chr(10) .
             '    %s' . chr(10) .
+            '    %s' . chr(10) .
             '}' . chr(10),
             'class ' . $identifier . ' extends \TYPO3Fluid\Fluid\Core\Compiler\AbstractCompiledTemplate',
             $this->generateCodeForLayoutName($storedLayoutName),
             ($parsingState->hasLayout() ? 'true' : 'false'),
             var_export($this->renderingContext->getViewHelperResolver()->getLocalNamespaces(), true),
             $this->generateArgumentDefinitionsCodeFromParsingState($parsingState),
+            $this->generateAvailableSlotsCodeFromParsingState($parsingState),
             $generatedRenderFunctions,
         );
         $this->renderingContext->getCache()->set($identifier, $templateCode);
@@ -259,6 +261,17 @@ protected function generateArgumentDefinitionsCodeFromParsingState(ParsingState
             '    }';
     }
 
+    protected function generateAvailableSlotsCodeFromParsingState(ParsingState $parsingState): string
+    {
+        $availableSlots = $parsingState->getAvailableSlots();
+        if ($availableSlots === []) {
+            return '';
+        }
+        return 'public function getAvailableSlots(): array {' . chr(10) .
+            '        return ' . var_export($availableSlots, true) . ';' . chr(10) .
+            '    }';
+    }
+
     /**
      * Replaces special characters by underscores
      * @see http://www.php.net/manual/en/language.variables.basics.php

src/Core/Compiler/TemplateCompiler.php

@@ -13,7 +13,6 @@
 use TYPO3Fluid\Fluid\Core\ViewHelper\TemplateStructureViewHelperResolver;
 use TYPO3Fluid\Fluid\Core\ViewHelper\UnresolvableViewHelperException;
 use TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperResolverDelegateInterface;
-use TYPO3Fluid\Fluid\ViewHelpers\SlotViewHelper;
 
 /**
  * Base class for a collection of components: Fluid templates that can be called with Fluid's
@@ -115,8 +114,7 @@ final public function getComponentDefinition(string $viewHelperName): ComponentD
                 $viewHelperName,
                 $parsedTemplate->getArgumentDefinitions(),
                 $this->additionalArgumentsAllowed($viewHelperName),
-                // For now, we just assume the default slot; This will change with the named slots feature.
-                [SlotViewHelper::DEFAULT_SLOT],
+                $parsedTemplate->getAvailableSlots(),
             );
         }
         return $this->componentDefinitionsCache[$viewHelperName];

src/Core/Component/AbstractComponentCollection.php

@@ -10,13 +10,16 @@
 namespace TYPO3Fluid\Fluid\Core\Component;
 
 use TYPO3Fluid\Fluid\Core\Compiler\TemplateCompiler;
+use TYPO3Fluid\Fluid\Core\Parser\Exception as ParserException;
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\NodeInterface;
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode;
+use TYPO3Fluid\Fluid\Core\Rendering\RenderingContext;
 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\ArgumentDefinition;
 use TYPO3Fluid\Fluid\Core\ViewHelper\Exception;
 use TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperResolverDelegateInterface;
+use TYPO3Fluid\Fluid\ViewHelpers\FragmentViewHelper;
 use TYPO3Fluid\Fluid\ViewHelpers\SlotViewHelper;
 
 /**
@@ -125,18 +128,43 @@ public function initializeArgumentsAndRender(): mixed
         return $this->getComponentDefinitionProvider()->getComponentRenderer()->renderComponent(
             $this->viewHelperNode->getName(),
             $this->arguments,
-            $this->viewHelperNode->getChildNodes() !== []
-                ? [SlotViewHelper::DEFAULT_SLOT => $this->buildRenderChildrenClosure()]
-                : [],
+            $this->buildSlotClosures(),
             $this->renderingContext,
         );
     }
 
-    private function buildRenderChildrenClosure(): callable
+    /**
+     * @return \Closure[]
+     */
+    private function buildSlotClosures(): array
+    {
+        if ($this->viewHelperNode->getChildNodes() === []) {
+            return [];
+        }
+        $slotClosures = [];
+        foreach ($this->extractFragmentViewHelperNodes($this->viewHelperNode) as $fragmentNode) {
+            $fragmentName = $this->extractFragmentName($fragmentNode);
+            if (isset($slotClosures[$fragmentName])) {
+                throw new ParserException(sprintf(
+                    'Fragment "%s" for <%s:%s> is defined multiple times.',
+                    $fragmentName,
+                    $this->viewHelperNode->getNamespace(),
+                    $this->viewHelperNode->getName(),
+                ), 1750865701);
+            }
+            $slotClosures[$fragmentName] = $this->buildSlotClosure($fragmentNode);
+        }
+        if ($slotClosures === []) {
+            $slotClosures[SlotViewHelper::DEFAULT_SLOT] = $this->buildSlotClosure($this->viewHelperNode);
+        }
+        return $slotClosures;
+    }
+
+    private function buildSlotClosure(ViewHelperNode $viewHelperNode): \Closure
     {
-        return function (): mixed {
+        return function () use ($viewHelperNode): mixed {
             $this->renderingContextStack[] = $this->renderingContext;
-            $result = $this->viewHelperNode->evaluateChildNodes($this->renderingContext);
+            $result = $viewHelperNode->evaluateChildNodes($this->renderingContext);
             $this->setRenderingContext(array_pop($this->renderingContextStack));
             return $result;
         };
@@ -152,7 +180,7 @@ public function convert(TemplateCompiler $templateCompiler): array
         $initializationPhpCode = '// Rendering Component ' . $this->viewHelperNode->getNamespace() . ':' . $this->viewHelperNode->getName() . chr(10);
 
         $argumentsVariableName = $templateCompiler->variableName('arguments');
-        $renderChildrenClosureVariableName = $templateCompiler->variableName('renderChildrenClosure');
+        $slotClosuresVariableName = $templateCompiler->variableName('slotClosures');
 
         // Similarly to Fluid's ViewHelper processing, the responsible ViewHelper resolver delegate
         // is resolved, validated early and "baked in" to the cache to improve rendering times for
@@ -163,9 +191,7 @@ public function convert(TemplateCompiler $templateCompiler): array
             var_export($resolverDelegate->getNamespace(), true),
             var_export($this->viewHelperNode->getName(), true),
             $argumentsVariableName,
-            $this->viewHelperNode->getChildNodes() !== []
-                ? '[\'' . SlotViewHelper::DEFAULT_SLOT . '\' => ' . $renderChildrenClosureVariableName . ']'
-                : '[]',
+            $slotClosuresVariableName,
         );
 
         $accumulatedArgumentInitializationCode = '';
@@ -194,11 +220,25 @@ public function convert(TemplateCompiler $templateCompiler): array
 
         $argumentInitializationCode .= '];' . chr(10);
 
+        $slotClosures = [];
+        if ($this->viewHelperNode->getChildNodes() !== []) {
+            foreach ($this->extractFragmentViewHelperNodes($this->viewHelperNode) as $fragmentNode) {
+                $fragmentName = $this->extractFragmentName($fragmentNode);
+                $slotClosures[$fragmentName] = $templateCompiler->wrapChildNodesInClosure($fragmentNode);
+            }
+            if ($slotClosures === []) {
+                $slotClosures[SlotViewHelper::DEFAULT_SLOT] = $templateCompiler->wrapChildNodesInClosure($this->viewHelperNode);
+            }
+        }
+
         // Build up closure which renders the child nodes
+        foreach ($slotClosures as $name => $closureCode) {
+            $slotClosures[$name] = var_export($name, true) . ' => ' . $closureCode;
+        }
         $initializationPhpCode .= sprintf(
-            '%s = %s;' . chr(10),
-            $renderChildrenClosureVariableName,
-            $templateCompiler->wrapChildNodesInClosure($this->viewHelperNode),
+            '%s = [' . chr(10) . '%s' . chr(10) . '];' . chr(10),
+            $slotClosuresVariableName,
+            implode(',' . chr(10), $slotClosures),
         );
 
         $initializationPhpCode .= $accumulatedArgumentInitializationCode . chr(10) . $argumentInitializationCode;
@@ -264,4 +304,22 @@ private function getComponentDefinitionProvider(): ViewHelperResolverDelegateInt
         }
         return $this->viewHelperNode->getResolverDelegate();
     }
+
+    /**
+     * @return ViewHelperNode[]
+     */
+    private function extractFragmentViewHelperNodes(ViewHelperNode $viewHelperNode): array
+    {
+        return array_filter(
+            $viewHelperNode->getChildNodes(),
+            fn(NodeInterface $node): bool => $node instanceof ViewHelperNode && $node->getUninitializedViewHelper() instanceof FragmentViewHelper,
+        );
+    }
+
+    private function extractFragmentName(ViewHelperNode $fragmentNode): string
+    {
+        return isset($fragmentNode->getArguments()['name'])
+            ? (string)$fragmentNode->getArguments()['name']->evaluate(new RenderingContext())
+            : SlotViewHelper::DEFAULT_SLOT;
+    }
 }

src/Core/Component/ComponentAdapter.php

@@ -31,6 +31,11 @@ public function getIdentifier(): string;
      */
     public function getArgumentDefinitions(): array;
 
+    /**
+     * @return string[]
+     */
+    public function getAvailableSlots(): array;
+
     /**
      * Render the parsed template with rendering context
      *

src/Core/Parser/ParsedTemplateInterface.php

@@ -33,6 +33,11 @@ class ParsingState implements ParsedTemplateInterface
      */
     protected array $argumentDefinitions = [];
 
+    /**
+     * @var string[]
+     */
+    protected array $availableSlots = [];
+
     /**
      * Root node reference
      */
@@ -103,6 +108,22 @@ public function setArgumentDefinitions(array $argumentDefinitions): void
         $this->argumentDefinitions = $argumentDefinitions;
     }
 
+    /**
+     * @return string[]
+     */
+    public function getAvailableSlots(): array
+    {
+        return $this->availableSlots;
+    }
+
+    /**
+     * @param string[] $availableSlots
+     */
+    public function setAvailableSlots(array $availableSlots): void
+    {
+        $this->availableSlots = $availableSlots;
+    }
+
     /**
      * Render the parsed template with rendering context
      *

src/Core/Parser/ParsingState.php

@@ -623,6 +623,11 @@ protected function buildArgumentObjectTree(ParsingState $state, string $argument
         //       affect the local state. Maybe it's also possible to get rid
         //       of the local state altogether.
         $innerState = $this->buildObjectTree($this->createParsingState(null), $splitArgument, self::CONTEXT_INSIDE_VIEWHELPER_ARGUMENTS);
+        // This can be removed once the outer-inner-state issue is resolved
+        $state->setAvailableSlots(array_unique(array_merge(
+            $state->getAvailableSlots(),
+            $innerState->getAvailableSlots(),
+        )));
         return $innerState->getRootNode();
     }