From 0508b7dcf3ad7a6c6e7d84d1967ea547611e8a4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Andr=C3=A9?= Date: Sun, 29 Dec 2024 23:29:21 +0100 Subject: [PATCH] [TwigComponent] Various fix / cleans in documentation --- src/TwigComponent/doc/index.rst | 194 +++++++++++--------------------- 1 file changed, 64 insertions(+), 130 deletions(-) diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst index b6b1b346f1..97256df10c 100644 --- a/src/TwigComponent/doc/index.rst +++ b/src/TwigComponent/doc/index.rst @@ -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 @@ -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 ` and finds the first match. If you have the recommended ``App\Twig\Components\``, then: @@ -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'; } @@ -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:: @@ -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 ```` should be viewed as living in its own, +The content inside of the ```` 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 ````, the ``this`` variable represents +First, inside of ````, the ``this`` variable represents the component you're *now* rendering *and* you have access to all of *that* component's variables: @@ -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 @@ -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 `` -.. 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:: @@ -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 @@ -1231,52 +1216,33 @@ Then use the ``color`` and ``size`` variants to select the classes needed: .. code-block:: html+twig - {# index.html.twig #} - -
My content
-
- // class="alert bg-red text-lg" - -
My content
-
- // class="alert bg-green text-sm" - - -
My content
+ ...
- // class="alert bg-red text-md flex items-center justify-center" - + + {# will render as: #} + +
+ ... +
+ 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({ - // ... - }) %} -
- {% block content %}{% endblock %} + {% block content %}{% endblock %}
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 @@ -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' }] }) %} @@ -1312,19 +1269,14 @@ when multiple other variant conditions are met. {# index.html.twig #} -
My content
-
- // class="alert bg-red text-lg font-bold" - - -
My content
-
- // class="alert bg-green text-sm" - - -
My content
+ ...
- // class="alert bg-green text-lg font-bold" + + {# will render as: #} + +
+ ... +
Default Variants ~~~~~~~~~~~~~~~~ @@ -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' } }) %} -
- {% block content %}{% endblock %} -
- {# index.html.twig #} - -
My content
+ + ... - // class="alert bg-red text-lg font-bold rounded-md" + + {# will render as: #} + +
+ ... +
Test Helpers ------------ @@ -1600,10 +1543,6 @@ 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. @@ -1611,10 +1550,6 @@ 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 @@ -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 @@ -1727,11 +1662,11 @@ can reference its components directly within your Twig templates: .. code-block:: html+twig - + Click me - + -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:: @@ -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 ```` should have its template -file at ``templates/components/Button.html.twig`` within the Shadcn bundle. +example, the component referenced as ```` should have its template +file at ``templates/components/Button.html.twig`` within the Acme bundle. Debugging Components -------------------- @@ -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