[TwigComponent] Add documentation about passing blocks to embedded components #985

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

Jump to bottom

Merged

weaverryan merged 9 commits into symfony:2.x from sneakyvv:embedded-components-doc

Jul 11, 2023

Contributor

sneakyvv commented Jul 2, 2023

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

This adds documentation of the feature added in #920

sneakyvv changed the title ~~Add documentation about passing blocks to embedded components~~ [TwigComponent] Add documentation about passing blocks to embedded components

weaverryan reviewed

View reviewed changes

Member

weaverryan left a comment

Parts are a bit more technically worded than I’d like - and I dropped you an idea on slack, but this is very nice: you chose excellent examples to show off what’s possible. Thanks!

src/TwigComponent/doc/index.rst Outdated

		@@ -832,6 +832,140 @@ The ``with`` data is what's mounted on the component object.

		Embedded components cannot currently be used with LiveComponents.

		Passing blocks to embedded components

Member

weaverryan Jul 3, 2023

Uppercase Blocks, Embedded and Components

src/TwigComponent/doc/index.rst Outdated


		.. versionadded:: 2.10

		The `outerBlocks` variable has been added since 2.10.

Member

weaverryan Jul 3, 2023

Suggested change

      
                The `outerBlocks` variable has been added since 2.10.
          
                The ``outerBlocks`` variable was added in 2.10.

src/TwigComponent/doc/index.rst Outdated

+                  {% endcomponent %}
+              What if this SuccessAlert component wants to make the content of its nested Alert component configurable?
+              Well, you can use the special `outerBlocks` variable for those cases. This makes it possible to refer

Member

weaverryan Jul 3, 2023

In rst, unlike markdown, all technical words have 2 “ticks” around them, not just 1

src/TwigComponent/doc/index.rst Outdated

+                      Look mom, I'm a complex component!
+                  {% endcomponent %}
+              Note that to pass a block multiple components down, each component would need to pass it along.

Member

weaverryan Jul 3, 2023

I’m not sure about this part - it seems obvious enough to me, and the code below REALLY makes this look complex. I vote for mentioning this perhaps, but not showing it.

Contributor Author

sneakyvv Jul 3, 2023

I guess you're right. Essentially, it was kinda explaining how blocks work, which is not the scope of this documentation.

src/TwigComponent/doc/index.rst Outdated

+                  {# templates/target.html.twig #}
+                  <div>{% block foo %}default content for foo{% endblock %}</div>
+              Context of embedded components

Member

weaverryan Jul 3, 2023

Uppercase everything except of

src/TwigComponent/doc/index.rst Outdated

+              Every embedded component can be viewed as another template inside a template, hence the name.
+              Or in other words, in the other direction, it's as if the embedded component's blocks are copy-pasted
+              into that component's template. This has a few interesting consequences.

Member

weaverryan Jul 3, 2023

into the target component’s template

src/TwigComponent/doc/index.rst Outdated

+              Or in other words, in the other direction, it's as if the embedded component's blocks are copy-pasted
+              into that component's template. This has a few interesting consequences.
+              First of all, although `this` is referring to the component of the template into which an (embedded)

Member

weaverryan Jul 3, 2023

First, although this refers to…

src/TwigComponent/doc/index.rst Outdated

+              First of all, although `this` is referring to the component of the template into which an (embedded)
+              component is nested, *INSIDE* an embedded component it is referring to the *embedded* component,
+              *NOT* the component into which it's being nested.

Member

weaverryan Jul 3, 2023

The wording on this is really tricky: nested vs embedded. Maybe say less and let the code do the talking.

src/TwigComponent/doc/index.rst Outdated


		.. code-block:: twig

		{# templates/successAlert.html.twig #}

Member

weaverryan Jul 3, 2023

SuccessAlert.html.twig - I think that’s in a few places.

Member

weaverryan commented Jul 5, 2023

Hey! I just did a quick proof and edit of the docs so far - a team effort to explain these important concepts on a simple way. I've tried to remove the wording "embedded component". Even I mix up "embedded" and "nested" in my mind. It's not as succinct, but saying "when you pass a block to a component" instead of "when you render an embedded component" I think is much more clear.

Contributor Author

sneakyvv commented Jul 5, 2023

Hey! I just did a quick proof and edit of the docs so far - a team effort to explain these important concepts on a simple way. I've tried to remove the wording "embedded component". Even I mix up "embedded" and "nested" in my mind. It's not as succinct, but saying "when you pass a block to a component" instead of "when you render an embedded component" I think is much more clear.

Love it. Indeed I also always have to think twice to correctly separate nested vs embedded components. It took a while to get this terminology right in my head, but it will take perhaps equally long to stop referring to them as embedded components :-)
Perhaps on a technical level, calling them that is actually still the most correct, especially seeing their similarity to the embed syntax, and even more so since the ComponentNode is in fact extending the EmbedNode. 🤓
But again, I'm all for simplicity and even more for clarity in the documentation!

Member

weaverryan commented Jul 5, 2023

Perhaps on a technical level, calling them that is actually still the most correct

I think so yes. So we may sometimes still use that term - but let's see if we can avoid it for the "outside" world :)

sneakyvv and others added 6 commits

July 6, 2023 20:45


          Add documentation about passing blocks to embedded components and the…

444686c

…ir context


          Add version info

1e85030


          Added suggestions of PR feedback

305661c


          Moving away from "embedded component" wording in docs

8e1d94b


          Fix typos

b0913d4


          Allow referring to outerblocks from non-nested components

111ac3a

Contributor Author

sneakyvv commented Jul 6, 2023

@weaverryan As discussed on Slack, I also allowed references to outer blocks from with a regular (non-nested) component.
Note that these blocks probably only make sense within an extending template, because otherwise the block would be rendered where it is defined ànd where it is referred as an outerblock. It even that might be desirable in some specific use cases, who knows 🤷

sneakyvv force-pushed the embedded-components-doc branch 2 times, most recently from 10ecefd to 111ac3a Compare

July 6, 2023 20:56


          Add simple example of outerBlocks without nested components to ease in

ae5a458

sneakyvv force-pushed the embedded-components-doc branch from 2a2accb to ae5a458 Compare

July 9, 2023 20:15

weaverryan added 2 commits

July 10, 2023 15:32


          proofing

acaa41a


          Fixing rst syntax

0bbb2b8

Member

weaverryan commented Jul 11, 2023

Thanks Bart!

weaverryan merged commit 5e41864 into symfony:2.x

sneakyvv mentioned this pull request

Fix typo in outerBlocks doc #1008

Merged

weaverryan added a commit that referenced this pull request


          minor #1008 Fix typo in outerBlocks doc (sneakyvv)

ff9ac42

This PR was merged into the 2.x branch.

Discussion
----------

Fix typo in outerBlocks doc

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

I noticed the recently merged doc from #985 had a small typo in one of the snippets.

Commits
-------

1f45fad Fix typo in outerBlocks doc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet