[TwigComponent] Add note in doc about composition that component live in their own context #1899
Conversation
WebMamba
commented
Jun 8, 2024
WebMamba
commented
| Q | A |
|---|---|
| Bug fix? | no |
| New feature? | no |
| Issues | Fix #1875 |
| License | MIT |
src/TwigComponent/doc/index.rst
Outdated
| <twig:Icon name="success"/> Nice work! | ||
| </twig:Alert> | ||
|
|
||
| You can have components inside your components! This is great! However, be aware that every component lives in its own context. This means that your child component does not know that it is inside a parent component; you cannot use any method like parent() inside the child component to access the parent. You should keep your components independent of the context. This rule is really important to respect, as it will guarantee that your components will always work the same way regardless of where you use them. If you need to access some parent data, you should pass properties down to your child or use events. |
There was a problem hiding this comment.
Nice !
Two small comments:
- maybe split in two lines, to emphasis some words, and improve even more readability ?
- i think we want to add a bit of nuance here or you may frighten people 😆
Instead of
You should keep your components independent of the context
Maybe
You should try to keep (...)
or
It is generally recommanded to ...
Same for the last sentence ?
There was a problem hiding this comment.
It's more like you must. Actually using the context is just unsupported. And I slightly disagree with the tone of this piece of documentation that suggest composition to explain inheritance does not work.
IMO it should be named something like Composition enforced if you want to get people straight to your point 😉 .
There was a problem hiding this comment.
In fact it's a bit more complicated than that.
There is a difference between anonymous and class-based components, there is a difference betwen "include" and "embed" components, and i don't even start with live ones haha
But this works perfectly
{% set aa = 'AA' %}
<twig:Browser>
{{ dump(aa) }}
</twig:Browser>
A component should not know an outside one existence.
There it's something else :)
There was a problem hiding this comment.
Ok, it just feels weird to me to have an example unrelated to the comment following then.
There was a problem hiding this comment.
My point was only that I prefer to avoid binary formulations, as things in life are rarely that simple, and few things in those components are that clear-cut. :)
| .. note:: | ||
|
|
||
| Because your TwigComponent live inside his own specific context, you can't use the parent function inside the block of your component template. | ||
|
|
There was a problem hiding this comment.
There was a problem hiding this comment.
Maybe my formulation is bad but I was trying to explain the issue @Nek- had. How to you explain that in a few lines?
There was a problem hiding this comment.
You should maybe say that parent refers to its own context instead. Adding that it acts like embed element may also be a nice addition.
| Let's take an exemple. Some component don't know their children ahead of time. This is common for components like Alert or Dialog that represent generic “boxes”. We recommend you | ||
| to use the block content to pass children directly into their output : | ||
|
|
||
| .. code-block:: html+twig | ||
|
|
||
| <div class="alert"> | ||
| {% block content %} | ||
| {% endblock %} | ||
| </div> | ||
|
|
||
| This lets other components pass arbitrary children to them by nesting the elements : | ||
|
|
||
| .. code-block:: html+twig | ||
|
|
||
| <twig:Alert> | ||
| <twig:Icon name="success"/> | ||
| <p>Nice work!</p> | ||
| </twig:Alert> | ||
|
|
||
| Anything inside the <twig:Alert> tag gets passed into the Alert component as a content block. Since Alert renders {% block content %} inside a <div>, the passed elements appear in the final output. | ||
| You can go deeper on the usage of block, on this part of the :ref:`documentation <embedded-components>` | ||
|
|
There was a problem hiding this comment.
Does this require a new section ? I feel this is more or less the same as what's already explained in the Passing HTML to Components Via Blocks section, or did i missread something ?
There was a problem hiding this comment.
I think so. I feel like this is one of the biggest traps people are falling into. This part is more about what to choose, and the block part is more about how to do it.
I tried to add more guidelines to the doc
| Composition vs Inheritance | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Symfony tend to follow the best pratice of the component architecture, so it's highly recommended to use Composition instead of Inheritance to reuse code betwen component (see: https://legacy.reactjs.org/docs/composition-vs-inheritance.html). |
There was a problem hiding this comment.
This link should use the RST syntax or the doctor ill not be happy :)
