Skip to content

Commit

Permalink
minor #2471 [TwigComponent] Various fix / cleans in documentation (sm…
Browse files Browse the repository at this point in the history 
…nandre)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[TwigComponent] Various fix / cleans in documentation

This pull request includes several updates to the documentation in the `src/TwigComponent/doc/index.rst` file. The changes primarily focus on removing versionadded directives, updating component examples, and improving the readability of the documentation.

Documentation updates:

* Removed multiple `versionadded` directives to streamline the documentation. [[1]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L139-L143) [[2]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L564-L567) [[3]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L817-R813) [[4]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L857-L860) [[5]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1603-L1617) [[6]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1711-R1654)
* Updated component examples to use simplified syntax and corrected component names. [[1]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L755-R750) [[2]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1234-R1245) [[3]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1730-R1670) [[4]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1743-R1680)
* Improved explanations and examples for component variants, including compound and default variants. [[1]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1289-R1260) [[2]](diffhunk://#diff-af91659afbc07f8a37d8086ade26a202cddfdd70b4a020c8e197d660162c1710L1337-R1316)
* Updated a note about the `stimulus_controller()` function requiring the `symfony/stimulus-bundle` package.
* Removed outdated references and updated links to external resources.

(PR summary written by)

Commits
-------

0508b7d [TwigComponent] Various fix / cleans in documentation
  • Loading branch information
@Kocal
Kocal committed Jan 5, 2025
2 parents 1d84847 + 0508b7d commit 8fcac2a
Showing 1 changed file with 64 additions and 130 deletions.
194 changes: 64 additions & 130 deletions src/TwigComponent/doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,9 @@ Done! Now render it wherever you want:
Enjoy your new component!

.. image:: images/alert-example.png
:alt: Example of the Alert Component
:alt: Example of the Alert Component

Example of the Alert Component
Example of the Alert Component

This brings the familiar "component" system from client-side frameworks
into Symfony. Combine this with `Live Components`_, to create
Expand Down Expand Up @@ -136,11 +136,6 @@ Take a moment to fist pump - then come back!
Naming Your Component
~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.8

Before 2.8, passing a name to ``AsTwigComponent`` was required. Now, the
name is optional and defaults to the class name.

To give your component a name, TwigComponent looks at the namespace(s)
configured in :ref:`twig_component.yaml <default_config>` and finds the
first match. If you have the recommended ``App\Twig\Components\``, then:
Expand Down Expand Up @@ -474,7 +469,7 @@ called ``mount()``::
public string $message;
public string $type = 'success';

public function mount(bool $isSuccess = true)
public function mount(bool $isSuccess = true): void
{
$this->type = $isSuccess ? 'success' : 'danger';
}
Expand Down Expand Up @@ -561,10 +556,6 @@ The data returned from ``preMount()`` will be used as the props for mounting.
PostMount Hook
~~~~~~~~~~~~~~

.. versionadded:: 2.1

The ``PostMount`` hook was added in TwigComponents 2.1.

After a component is instantiated and its data mounted, you can run extra
code via the ``PostMount`` hook::

Expand Down Expand Up @@ -752,11 +743,11 @@ There is also a non-HTML syntax that can be used:
Context / Variables Inside of Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The content inside of the ``<twig:{Component}>`` should be viewed as living in its own,
The content inside of the ``<twig:Component>`` should be viewed as living in its own,
independent template, which extends the component's template. This has a few interesting
consequences.

First, inside of ``<twig:{Component}>``, the ``this`` variable represents
First, inside of ``<twig:Component>``, the ``this`` variable represents
the component you're *now* rendering *and* you have access to all of *that*
component's variables:

Expand Down Expand Up @@ -814,10 +805,12 @@ When overriding the ``alert_message`` block, you have access to the ``message``

.. versionadded:: 2.13

The ability to refer to the scope of higher components via the ``outerScope`` variable was added in 2.13.
The ability to refer to the scope of higher components via the ``outerScope``
variable was added in 2.13.

As mentioned before, variables from lower components are merged with those from upper components. When you need
access to some properties or functions from higher components, that can be done via the ``outerScope...`` variable:
As mentioned before, variables from lower components are merged with those from
upper components. When you need access to some properties or functions from higher
components, that can be done via the ``outerScope...`` variable:

.. code-block:: twig
Expand Down Expand Up @@ -854,10 +847,6 @@ Remember though that the ``outerScope`` reference only starts once you're INSIDE
Inheritance & Forwarding "Outer Blocks"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.10

The ``outerBlocks`` variable was added in 2.10.

The content inside a ``<twig:`` 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. However, you
Expand Down Expand Up @@ -972,12 +961,13 @@ To add a custom `Stimulus controller`_ to your root component element:

<div {{ attributes.defaults(stimulus_controller('my-controller', {someValue: 'foo'})) }}>

.. versionadded:: 2.9
.. note::

The ``stimulus_controller()`` function requires ``symfony/stimulus-bundle``.

.. code-block:: terminal
The ability to use ``stimulus_controller()`` with ``attributes.defaults()``
was added in TwigComponents 2.9 and requires ``symfony/stimulus-bundle``.
Previously, ``stimulus_controller()`` was passed to an ``attributes.add()``
method.
$ composer require symfony/stimulus-bundle
.. note::

Expand Down Expand Up @@ -1186,21 +1176,16 @@ The nesting is recursive so you could potentially do something like this:
Component with Complex Variants (CVA)
-------------------------------------

.. versionadded:: 2.16

The ``cva`` function was added in TwigComponents 2.16.

.. deprecated:: 2.20

The ``cva`` function was deprecated in TwigComponents 2.20, and will be removed in 3.0.
The function is now provided by the ``twig/html-extra:^3.12`` package under the name `html_cva`_.
The ``cva`` function was deprecated in TwigComponents 2.20, and will be
removed in 3.0. The function is now provided by the ``twig/html-extra:^3.12``
package under the name `html_cva`_.

`CVA (Class Variant Authority)`_ is a concept from the JavaScript world and used
by the well-known `shadcn/ui`_.
CVA allows you to display a component with different variants (color, size, etc.),
to create highly reusable and customizable components. This is powered by a ``cva()`` Twig
function where you define ``base`` classes that should always be present and then different
``variants`` and the corresponding classes:
`CVA (Class Variant Authority)`_ originates from the JavaScript ecosystem. It
enables reusable, customizable components by managing variants (e.g., color, size).
The ``cva()`` Twig function defines ``base`` classes (always applied) and variant-specific
classes:

.. code-block:: html+twig

Expand Down Expand Up @@ -1231,52 +1216,33 @@ Then use the ``color`` and ``size`` variants to select the classes needed:

.. code-block:: html+twig

{# index.html.twig #}
<twig:Alert color="red" size="lg">
<div>My content</div>
</twig:Alert>
// class="alert bg-red text-lg"

<twig:Alert color="green" size="sm">
<div>My content</div>
</twig:Alert>
// class="alert bg-green text-sm"

<twig:Alert color="red" class="flex items-center justify-center">
<div>My content</div>
...
</twig:Alert>
// class="alert bg-red text-md flex items-center justify-center"


{# will render as: #}

<div class="alert bg-green text-sm">
...
</div>

CVA and Tailwind CSS
~~~~~~~~~~~~~~~~~~~~

CVA work perfectly with Tailwind CSS. The only drawback is that you can have class conflicts.
To "merge" conflicting classes together and keep only the ones you need, use the
``tailwind_merge()`` method from `tales-from-a-dev/twig-tailwind-extra`_
with the ``cva()`` function:

.. code-block:: terminal
$ composer require tales-from-a-dev/twig-tailwind-extra
CVA integrates seamlessly with Tailwind CSS, though class conflicts may occur.
Use the ``tailwind_merge()`` function from `tales-from-a-dev/twig-tailwind-extra`_
to resolve conflicts:

.. code-block:: html+twig

{# templates/components/Alert.html.twig #}
{% props color = 'blue', size = 'md' %}

{% set alert = cva({
// ...
}) %}

<div class="{{ alert.apply({color, size}, attributes.render('class'))|tailwind_merge }}">
{% block content %}{% endblock %}
{% block content %}{% endblock %}
</div>

Compound Variants
~~~~~~~~~~~~~~~~~

You can define compound variants. A compound variant is a variant that applies
when multiple other variant conditions are met.
Define compound variants for conditions involving multiple variants:

.. code-block:: html+twig

Expand All @@ -1286,21 +1252,12 @@ when multiple other variant conditions are met.
{% set alert = cva({
base: 'alert',
variants: {
color: {
blue: 'bg-blue',
red: 'bg-red',
green: 'bg-green',
},
size: {
sm: 'text-sm',
md: 'text-md',
lg: 'text-lg',
}
color: { red: 'bg-red' },
size: { lg: 'text-lg' }
},
compoundVariants: [{
// if color = red AND size = (md or lg), add the `font-bold` class
color: ['red'],
size: ['md', 'lg'],
size: ['lg'],
class: 'font-bold'
}]
}) %}
Expand All @@ -1312,19 +1269,14 @@ when multiple other variant conditions are met.
{# index.html.twig #}

<twig:Alert color="red" size="lg">
<div>My content</div>
</twig:Alert>
// class="alert bg-red text-lg font-bold"

<twig:Alert color="green" size="sm">
<div>My content</div>
</twig:Alert>
// class="alert bg-green text-sm"

<twig:Alert color="red" size="md">
<div>My content</div>
...
</twig:Alert>
// class="alert bg-green text-lg font-bold"

{# will render as: #}

<div class="alert bg-red text-lg font-bold">
...
</div>

Default Variants
~~~~~~~~~~~~~~~~
Expand All @@ -1334,42 +1286,33 @@ If no variants match, you can define a default set of classes to apply:
.. code-block:: html+twig

{# templates/components/Alert.html.twig #}
{% props color = 'blue', size = 'md' %}

{% set alert = cva({
base: 'alert',
variants: {
color: {
blue: 'bg-blue',
red: 'bg-red',
green: 'bg-green',
},
size: {
sm: 'text-sm',
md: 'text-md',
lg: 'text-lg',
red: 'bg-red'
},
rounded: {
sm: 'rounded-sm',
md: 'rounded-md',
lg: 'rounded-lg',
md: 'rounded-md'
}
},
defaultVariants: {
rounded: 'md',
rounded: 'md'
}
}) %}

<div class="{{ alert.apply({color, size}) }}">
{% block content %}{% endblock %}
</div>

{# index.html.twig #}

<twig:Alert color="red" size="lg">
<div>My content</div>
<twig:Alert color="red">
...
</twig:Alert>
// class="alert bg-red text-lg font-bold rounded-md"

{# will render as: #}

<div class="alert bg-red rounded-md">
...
</div>

Test Helpers
------------
Expand Down Expand Up @@ -1600,21 +1543,13 @@ the twig template and twig variables before components are rendered::
PostRenderEvent
~~~~~~~~~~~~~~~

.. versionadded:: 2.5

The ``PostRenderEvent`` was added in TwigComponents 2.5.

The ``PostRenderEvent`` is called after a component has finished
rendering and contains the ``MountedComponent`` that was just
rendered.

PreCreateForRenderEvent
~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5

The ``PreCreateForRenderEvent`` was added in TwigComponents 2.5.

Subscribing to the ``PreCreateForRenderEvent`` gives the ability to be
notified before a component object is created or hydrated, at the
very start of the rendering process. You have access to the component
Expand Down Expand Up @@ -1708,14 +1643,14 @@ If a component class matches multiple namespaces, the first matched will
be used.

3rd-Party Bundle
~~~~~~~~~~~~~~~~
----------------

The flexibility of Twig Components is extended even further when integrated
with third-party bundles, allowing developers to seamlessly include pre-built
components into their projects.

Anonymous Components
--------------------
~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.20

Expand All @@ -1727,11 +1662,11 @@ can reference its components directly within your Twig templates:

.. code-block:: html+twig

<twig:Shadcn:Button type="primary">
<twig:Acme:Button type="primary">
Click me
</twig:Shadcn:Button>
</twig:Acme:Button>

Here, the component name is composed of the bundle's Twig namespace ``Shadcn``, followed
Here, the component name is composed of the bundle's Twig namespace ``Acme``, followed
by a colon, and then the component path Button.

.. note::
Expand All @@ -1740,8 +1675,8 @@ by a colon, and then the component path Button.
``bin/console debug:twig`` command.

The component must be located in the bundle's ``templates/components/`` directory. For
example, the component referenced as ``<twig:Shadcn:Button>`` should have its template
file at ``templates/components/Button.html.twig`` within the Shadcn bundle.
example, the component referenced as ``<twig:Acme:Button>`` should have its template
file at ``templates/components/Button.html.twig`` within the Acme bundle.

Debugging Components
--------------------
Expand Down Expand Up @@ -1807,7 +1742,6 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`Stimulus controller`: https://symfony.com/bundles/StimulusBundle/current/index.html
.. _`CVA (Class Variant Authority)`: https://cva.style/docs/getting-started/variants
.. _`html_cva`: https://twig.symfony.com/doc/3.x/functions/html_cva.html
.. _`shadcn/ui`: https://ui.shadcn.com
.. _`tales-from-a-dev/twig-tailwind-extra`: https://github.com/tales-from-a-dev/twig-tailwind-extra
.. _`ignore not defined options`: https://symfony.com/doc/current/components/options_resolver.html#ignore-not-defined-options
.. _`Symfony MakerBundle`: https://symfony.com/bundles/SymfonyMakerBundle/current/index.html

0 comments on commit 8fcac2a

Please sign in to comment.