feature #985 [TwigComponent] Add documentation about passing blocks to embedded components (sneakyvv, weaverryan)

This PR was merged into the 2.x branch.

Discussion
----------

[TwigComponent] Add documentation about passing blocks to embedded components

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Tickets       | Fix #...
| License       | MIT

This adds documentation of the feature added in #920

Commits
-------

0bbb2b8 Fixing rst syntax
acaa41a proofing
ae5a458 Add simple example of outerBlocks without nested components to ease in
111ac3a Allow referring to outerblocks from non-nested components
b0913d4 Fix typos
8e1d94b Moving away from "embedded component" wording in docs
305661c Added suggestions of PR feedback
1e85030 Add version info
444686c Add documentation about passing blocks to embedded components and their context

Author: weaverryan

src/TwigComponent/doc/index.rst

@@ -765,13 +765,15 @@ independently. If you're using `Live Components`_, then there
 *are* some guidelines related to how the re-rendering of parent and
 child components works. Read `Live Nested Components`_.
 
-Embedded Components
--------------------
+.. _embedded-components:
+
+Passing Blocks to Components
+----------------------------
 
 .. tip::
 
-    Embedded components (i.e. components with blocks) can be written in a more
-    readable way by using the `Component HTML Syntax`_.
+    The `Component HTML Syntax`_ allows you to pass blocks to components in an
+    even more readable way.
 
 You can write your component's Twig template with blocks that can be overridden
 when rendering using the ``{% component %}`` syntax. These blocks can be thought of as
@@ -830,7 +832,122 @@ The ``with`` data is what's mounted on the component object.
 
 .. note::
 
-    Embedded components *cannot* currently be used with LiveComponents.
+    The ``{% component %}`` syntax *cannot* currently be used with LiveComponents.
+
+Inheritance & Forwarding "Outer Blocks"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.10
+
+    The ``outerBlocks`` variable was added in 2.10.
+
+The content inside a ``{% component ... %}`` tag should be viewed as living in
+its own, independent template, which extends the component's template. This means that
+any blocks that live in the "outer" template are not available inside the ``{% component %}`` tag.
+However, a special ``outerBlocks`` variable is added as a way to refer to those blocks:
+
+.. code-block:: html+twig
+
+  {% extends 'base.html.twig' %}
+
+  {% block call_to_action %}<strong>Attention! Free Puppies!</strong>{% endblock %}
+
+  {% block body %}
+    {% component Alert %}
+      {% block content %}{{ block(outerBlocks.call_to_action) }}{% endblock %}
+    {% endcomponent %}
+  {% endblock %}
+
+The ``outerBlocks`` variable becomes specially useful with nested components. For example,
+imagine we want to create a ``SuccessAlert`` component that's usable like this:
+
+.. code-block:: html+twig
+
+    {# templates/some_page.html.twig #}
+    {% component SuccessAlert %}
+        {% content %}We will successfully <em>forward</em> this block content!{% endblock %}
+    {% endcomponent %}
+
+But we already have a generic ``Alert`` component, and we want to re-use it:
+
+.. code-block:: html+twig
+
+    {# templates/Alert.html.twig #}
+    <div class="alert alert-{{ type }}">
+        {% block content %}{% endblock %}
+    </div>
+
+To do this, the ``SuccessAlert`` component can grab the ``content`` block that's passed to it
+via the ``outerBlocks`` variable and forward it into ``Alert``:
+
+.. code-block:: twig
+
+    {# templates/SuccessAlert.html.twig #}
+    {% component Alert with { type: 'success' } %}
+        {% block content %}{{ blocks(outerBlocks.content) }}{% endblock %}
+    {% endcomponent %}
+
+Note that to pass a block multiple components down, each component needs to pass it.
+
+Context / Variables Inside of Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The content inside of the ``{% component ... %}`` should be viewed as living in its own,
+independent template, which extends the component's template. This has a few interesting consequences.
+
+First, once you're inside of ``{% component ... %}``, the ``this`` variable represents
+the component you're now rendering *and* you have access to all of that component's variables:
+
+.. code-block:: twig
+
+    {# templates/SuccessAlert.html.twig #}
+    {{ this.someFunction }} {# this refers to SuccessAlert #}
+
+    {% component Alert with { type: 'success' } %}
+        {{ this.someFunction }} {# this refers to Alert! #}
+
+        {{ type }} {# references a "type" prop from Alert #}
+    {% endcomponent %}
+
+Conveniently, in addition to the variables from the ``Alert`` component, you still have
+access to whatever variables are available in the original template:
+
+.. code-block:: twig
+
+    {# templates/SuccessAlert.html.twig #}
+    {% set name = 'Fabien' %}
+    {% component Alert with { type: 'success' } %}
+        Hello {{ name }}
+    {% endcomponent %}
+
+Note that ALL variables from upper components (e.g. ``SuccessAlert``) are available to lower
+components (e.g. ``Alert``). However, because variables are merged, variables with the same name
+are overridden by lower components (that's also why ``this`` refers to the embedded, or
+"current" component).
+
+The most interesting thing is that the content inside of ``{% component ... %}`` is
+executed as if it is "copy-and-pasted" into the block of the target template. This means
+you can access variables from the block you're overriding! For example:
+
+.. code-block:: twig
+
+    {# templates/SuccessAlert.html.twig #}
+    {% for message in messages %}
+        {% block alert_message %}
+            A default {{ message }}
+        {% endblock %}
+    {% endfor %}
+
+When overriding the ``alert_message`` block, you have access to the ``message`` variable:
+
+.. code-block:: twig
+
+    {# templates/some_page.html.twig #}
+    {% component SuccessAlert %}
+        {% block alert_message %}
+            I can override the alert_message block and access the {{ message }} too!
+        {% endblock %}
+    {% endcomponent %}
 
 Component HTML Syntax
 ---------------------

src/TwigComponent/src/BlockStack.php

@@ -36,13 +36,6 @@ public function convert(array $blocks, int $targetEmbeddedTemplateIndex): array
             // identifies the block definition.
             $hostEmbeddedTemplateIndex = $this->findHostEmbeddedTemplateIndex();
 
-            if (0 === $hostEmbeddedTemplateIndex) {
-                // If there is no embedded template index, that means we're in a normal template.
-                // It wouldn't make sense to make these available as outer blocks,
-                // since the block is already printed in place.
-                continue;
-            }
-
             // Change the name of outer blocks to something unique so blocks of nested components aren't overridden,
             // which otherwise might cause a recursion loop when nesting components.
             $newName = self::OUTER_BLOCK_PREFIX.$blockName.'_'.mt_rand();

src/TwigComponent/tests/Fixtures/Component/BasicComponent.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\TwigComponent\Tests\Fixtures\Component;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+/**
+ * @author Bart Vanderstukken <[email protected]>
+ */
+#[AsTwigComponent]
+final class BasicComponent
+{
+}

src/TwigComponent/tests/Fixtures/templates/base.html.twig

@@ -0,0 +1 @@
+{% block body %}{% endblock %}

src/TwigComponent/tests/Fixtures/templates/components/BasicComponent.html.twig

@@ -0,0 +1,3 @@
+<div>
+    {% block content %}{% endblock %}
+</div>

src/TwigComponent/tests/Fixtures/templates/embedded_component_blocks_outer_blocks_extended_template.html.twig

@@ -0,0 +1,9 @@
+{% extends 'base.html.twig' %}
+
+{% block foo %}Hello world!{% endblock %}
+
+{% block body %}
+<twig:BasicComponent>
+    {{ block(outerBlocks.foo) }}
+</twig:BasicComponent>
+{% endblock %}

src/TwigComponent/tests/Integration/EmbeddedComponentTest.php

@@ -80,6 +80,16 @@ public function testBlockCanBeUsedWithinNestedViaTheOuterBlocks(): void
         );
     }
 
+    /**
+     * Rule 5 bis: A block inside an extending template can be use inside a component in that template and is NOT rendered in the original location.
+     */
+    public function testBlockCanBeUsedViaTheOuterBlocks(): void
+    {
+        $output = self::getContainer()->get(Environment::class)->render('embedded_component_blocks_outer_blocks_extended_template.html.twig');
+        $this->assertStringContainsStringIgnoringIndentation('<div>Hello world!</div>', $output);
+        $this->assertStringNotContainsString("Hello world!\n<div", $output);
+    }
+
     /**
      * Rule 8: Defining a block for a component overrides any default content that block has in the component's template.
      *         This also means that when passing block down that you will lose that default content.