Add documentation

src/TwigComponent/doc/index.rst

@@ -951,6 +951,42 @@ When overriding the ``alert_message`` block, you have access to the ``message``
         {% endblock %}
     {% endcomponent %}
 
+Sometimes, you may want to override a block of a deeply nested component and you need access to
+some properties or functions from higher components. That can be done via the ``this.parent...`` hierarchy:
+
+.. code-block:: twig
+
+    {# templates/SuccessAlert.html.twig #}
+    {% component Alert with { type: 'success' } %}
+        {{ this.parent.someFunction }} {# this refers to SuccessAlert #}
+
+        {{ this.parent.someProp }} {# references a "someProp" prop from SuccessAlert #}
+    {% endcomponent %}
+
+To keep the generic Alert component unaware of the ``someProp`` prop it is better to use ``this.parent``
+instead of passing that info along via Alert's attributes.
+
+You can keep referring to 'grand parents' as well. Just add another ``parent``.
+Remember though that the parent reference only starts once you're INSIDE the (embedded) component.
+
+.. code-block:: twig
+
+    {# templates/FancyProfileCard.html.twig #}
+    {% component Card %}
+        {% block header %}
+            {% component Alert with { message: this.parent.someProp } %} {# not yet INSIDE the Alert template #}
+                {% block content %}
+                    {{ message }} {# same value as below, indirectly refers to FancyProfileCard::someProp #}
+                    {{ this.parent.parent.someProp }} {# directly refers to FancyProfileCard::someProp #}
+                {% endblock %}
+            {% endcomponent %}
+        {% endblock %}
+    {% endcomponent %}
+
+.. versionadded:: 2.12
+
+    The ability to refer to higher components via the ``this.parent`` syntax was added in 2.12.
+
 Component HTML Syntax
 ---------------------