diff --git a/src/Autocomplete/doc/index.rst b/src/Autocomplete/doc/index.rst index 5bbeb84880c..1ef35841150 100644 --- a/src/Autocomplete/doc/index.rst +++ b/src/Autocomplete/doc/index.rst @@ -12,7 +12,7 @@ into an Ajax-powered autocomplete smart UI control (leveraging `Tom Select`_): Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. Then install the bundle using Composer and Symfony Flex: @@ -20,12 +20,11 @@ Then install the bundle using Composer and Symfony Flex: $ composer require symfony/ux-autocomplete -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -585,7 +584,7 @@ This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html .. _`Tom Select`: https://tom-select.js.org/ -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html .. _`Tom Select Options`: https://tom-select.js.org/docs/#general-configuration .. _`controller.ts`: https://github.com/symfony/ux/blob/2.x/src/Autocomplete/assets/src/controller.ts .. _`Tom Select Render Templates`: https://tom-select.js.org/docs/#render-templates diff --git a/src/Chartjs/doc/index.rst b/src/Chartjs/doc/index.rst index 8fe0caa8446..9dfd32b17ac 100644 --- a/src/Chartjs/doc/index.rst +++ b/src/Chartjs/doc/index.rst @@ -8,20 +8,19 @@ It is part of `the Symfony UX initiative`_. Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. -Then, install this bundle using Composer and Symfony Flex: +Then install the bundle using Composer and Symfony Flex: .. code-block:: terminal $ composer require symfony/ux-chartjs -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -244,7 +243,7 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html .. _`Chart.js`: https://www.chartjs.org .. _`the Symfony UX initiative`: https://symfony.com/ux .. _`Chart.js documentation`: https://www.chartjs.org/docs/latest/ -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html .. _`a lot of plugins`: https://github.com/chartjs/awesome#plugins .. _`zoom plugin`: https://www.chartjs.org/chartjs-plugin-zoom/latest/ .. _`zoom plugin documentation`: https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/integration.html diff --git a/src/Cropperjs/doc/index.rst b/src/Cropperjs/doc/index.rst index 1aa48de9ac7..5a75c21b5ec 100644 --- a/src/Cropperjs/doc/index.rst +++ b/src/Cropperjs/doc/index.rst @@ -8,7 +8,7 @@ Symfony UX Cropper.js is a Symfony bundle integrating the Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. Then, install this bundle using Composer and Symfony Flex: @@ -16,12 +16,11 @@ Then, install this bundle using Composer and Symfony Flex: $ composer require symfony/ux-cropperjs -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -151,4 +150,4 @@ https://symfony.com/doc/current/contributing/code/bc.html .. _`Cropper.js`: https://fengyuanchen.github.io/cropperjs/ .. _`the Symfony UX initiative`: https://symfony.com/ux .. _`the Cropper.js options`: https://github.com/fengyuanchen/cropperjs/blob/main/README.md#options -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html diff --git a/src/Dropzone/doc/index.rst b/src/Dropzone/doc/index.rst index 6b8f6c36480..bbc1c03f795 100644 --- a/src/Dropzone/doc/index.rst +++ b/src/Dropzone/doc/index.rst @@ -10,7 +10,7 @@ having to browse their computer for a file. Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. Then, install this bundle using Composer and Symfony Flex: @@ -18,12 +18,11 @@ Then, install this bundle using Composer and Symfony Flex: $ composer require symfony/ux-dropzone -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -157,4 +156,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html .. _`the Symfony UX initiative`: https://symfony.com/ux -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html diff --git a/src/LazyImage/doc/index.rst b/src/LazyImage/doc/index.rst index e0c1820b4e5..0e26cc5da0d 100644 --- a/src/LazyImage/doc/index.rst +++ b/src/LazyImage/doc/index.rst @@ -12,7 +12,7 @@ It provides two key features: Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. Then install this bundle using Composer and Symfony Flex: @@ -20,12 +20,11 @@ Then install this bundle using Composer and Symfony Flex: $ composer require symfony/ux-lazy-image -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -174,4 +173,4 @@ https://symfony.com/doc/current/contributing/code/bc.html .. _`the Symfony UX initiative`: https://symfony.com/ux .. _`BlurHash implementation`: https://blurha.sh .. _`StimulusBundle`: https://symfony.com/bundles/StimulusBundle/current/index.html -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html diff --git a/src/LiveComponent/doc/index.rst b/src/LiveComponent/doc/index.rst index 2244901e0f9..df115bdb1fb 100644 --- a/src/LiveComponent/doc/index.rst +++ b/src/LiveComponent/doc/index.rst @@ -4,11 +4,14 @@ Live Components **EXPERIMENTAL** This component is currently experimental and is likely to change, or even change drastically. -Live components work with the `TwigComponent`_ library +Live components builds on top of the `TwigComponent`_ library to give you the power to automatically update your Twig components on the frontend as the user interacts with them. Inspired by `Livewire`_ and `Phoenix LiveView`_. +If you're not familiar with Twig components yet, it's worth taking a few minutes +to familiarize yourself in the `TwigComponent documentation`_. + A real-time product search component might look like this:: // src/Components/ProductSearch.php @@ -55,16 +58,6 @@ A real-time product search component might look like this:: -.. versionadded:: 2.1 - - The ability to reference local variables in the template (e.g. ``query``) was added in TwigComponents 2.1. - Previously, all data needed to be referenced through ``this`` (e.g. ``this.query``). - -.. versionadded:: 2.1 - - The ability to initialize live component with the ``attributes`` twig variable was added in LiveComponents - 2.1. Previously, the ``init_live_component()`` function was required (this function was removed in 2.1). - Done! Now render it wherever you want: .. code-block:: twig @@ -79,7 +72,7 @@ Want some demos? Check out https://ux.symfony.com/live-component#demo Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. Now install the library with: @@ -87,12 +80,11 @@ Now install the library with: $ composer require symfony/ux-live-component -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -411,7 +403,8 @@ In this case, the model (e.g. ``publishAt``) will probably *not* update correctly because JavaScript doesn't trigger the normal ``change`` event. To fix this, you'll need to "hook" into the JavaScript library and set the model directly (or trigger a -``change`` event on the ``data-model`` field). See :ref:`working-in-javascript`. +``change`` event on the ``data-model`` field). See +:ref:`manually trigger an element change `. .. _hydration: @@ -789,6 +782,8 @@ initialized: const component = document.getElementById('id-of-your-element').__component; component.mode = 'editing'; +.. _javascript-manual-element-change: + Finally, you can also set the value of a model field directly. However, be sure to *also* trigger a ``change`` event so that live components is notified of the change: @@ -2949,6 +2944,7 @@ However it is currently considered `experimental`_, meaning it is not bound to Symfony's BC policy for the moment. .. _`TwigComponent`: https://symfony.com/bundles/ux-twig-component/current/index.html +.. _TwigComponent documentation: https://symfony.com/bundles/ux-twig-component/current/index.html .. _`Livewire`: https://laravel-livewire.com .. _`Phoenix LiveView`: https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html .. _`Twig Component`: https://symfony.com/bundles/ux-twig-component/current/index.html @@ -2956,7 +2952,7 @@ bound to Symfony's BC policy for the moment. .. _`Symfony form`: https://symfony.com/doc/current/forms.html .. _`experimental`: https://symfony.com/doc/current/contributing/code/experimental.html .. _`dependent form fields`: https://ux.symfony.com/live-component/demos/dependent-form-fields -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html .. _`localizes its URLs`: https://symfony.com/doc/current/translation/locale.html#translation-locale-url .. _`attributes variable`: https://symfony.com/bundles/ux-twig-component/current/index.html#component-attributes .. _`CollectionType`: https://symfony.com/doc/current/form/form_collections.html diff --git a/src/Notify/doc/index.rst b/src/Notify/doc/index.rst index 397a35bd906..1a90678a9a4 100644 --- a/src/Notify/doc/index.rst +++ b/src/Notify/doc/index.rst @@ -7,7 +7,7 @@ in Symfony applications using `Mercure`_. It is part of `the Symfony UX initiati Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +Before you start, make sure you have `StimulusBundle configured in your app`_. Then, install this bundle using Composer and Symfony Flex: @@ -15,12 +15,11 @@ Then, install this bundle using Composer and Symfony Flex: $ composer require symfony/ux-notify -If you're using WebpackEncore, install your assets and restart Encore. This is -not needed if you're using AssetMapper: +If you're using WebpackEncore, install your assets and restart Encore (not +needed if you're using AssetMapper): .. code-block:: terminal - # Don't forget to install the JavaScript dependencies as well and compile $ npm install --force $ npm run watch @@ -153,7 +152,7 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html .. _`the Symfony UX initiative`: https://symfony.com/ux -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html .. _`Mercure`: https://mercure.rocks .. _`running Mercure server`: https://symfony.com/doc/current/mercure.html#running-a-mercure-hub .. _`native notifications`: https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API diff --git a/src/React/doc/index.rst b/src/React/doc/index.rst index 1b1298d6553..48a021f21f3 100644 --- a/src/React/doc/index.rst +++ b/src/React/doc/index.rst @@ -13,7 +13,12 @@ Symfony UX React supports React 18+. Installation ------------ -Before you start, make sure you have `Symfony UX configured in your app`_. +.. note:: + + This package works best with WebpackEncore. To use it with AssetMapper, see + :ref:`Using with AssetMapper `. + +Before you start, make sure you have `StimulusBundle configured in your app`_. Then install the bundle using Composer and Symfony Flex: .. code-block:: terminal @@ -40,7 +45,6 @@ Install a package to help React: $ npm run watch # or use yarn - $ yarn add @babel/preset-react --dev --force $ yarn watch @@ -98,11 +102,40 @@ For example:
Loading...
- + {# Component living in a subdirectory: "assets/react/controllers/Admin/OtherComponent" #}
{% endblock %} +.. _using-with-asset-mapper: + +Using with AssetMapper +---------------------- + +Because the JSX format isn't pure JavaScript, using this library with AssetMapper +requires some extra steps. + +#. Compile your ``.jsx`` files to pure JavaScript files. This can be done by + installing Babel and the ``@babel/preset-react`` preset. Example: + https://github.com/symfony/ux/blob/2.x/ux.symfony.com/package.json + +#. Point this library at the "built" controllers directory that contains the final + JavaScript files: + +.. code-block:: yaml + + # config/packages/react.yaml + react: + controllers_path: '%kernel.project_dir%/assets/build/react/controllers' + +Also, inside of your ``.jsx`` files, when importing another component, use the +``.js`` extension: + +.. code-block:: javascript + + // use PackageList.js even though the file is named PackageList.jsx + import PackageList from '../components/PackageList.js'; + Backward Compatibility promise ------------------------------ @@ -112,4 +145,4 @@ https://symfony.com/doc/current/contributing/code/bc.html .. _`React`: https://reactjs.org/ .. _`the Symfony UX initiative`: https://symfony.com/ux -.. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html +.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html diff --git a/src/StimulusBundle/doc/index.rst b/src/StimulusBundle/doc/index.rst index 5289164b6e3..3f9aee5737f 100644 --- a/src/StimulusBundle/doc/index.rst +++ b/src/StimulusBundle/doc/index.rst @@ -1,11 +1,17 @@ StimulusBundle: Symfony integration with Stimulus ================================================= -This bundle adds integration between Symfony, `Stimulus`_ and Symfony UX: +.. tip:: -A) Twig ``stimulus_*`` functions & filters to add Stimulus controllers, actions & targets in your templates; -B) Integration with Symfony UX & AssetMapper (this integration is `experimental`_) -C) A helper service to build the Stimulus data attributes and use them in your services. + Check out live demos of Symfony UX at https://ux.symfony.com! + +This bundle adds integration between Symfony, `Stimulus`_ and the Symfony UX packages: + +A) Twig ``stimulus_`` functions & filters to add Stimulus controllers, + actions & targets in your templates; + +B) Integration to load :ref:`UX Packages ` (extra Stimulus controllers) + (if you're using AssetMapper, this integration is `experimental`_) Installation ------------ @@ -15,18 +21,13 @@ both work great with StimulusBundle: * A) `Webpack Encore`_ Node-based packaging system: - .. code-block:: terminal - - $ composer require symfony/webpack-encore-bundle or * B) `AssetMapper`_: PHP-based system for handling assets: - .. code-block:: terminal - - $ composer require symfony/asset-mapper +See `Encore vs AssetMapper`_ to learn which is best for your project. -Then, install the bundle: +Next, install the bundle: .. code-block:: terminal @@ -35,11 +36,26 @@ Then, install the bundle: If you're using `Symfony Flex`_, you're done! The recipe will update the necessary files. If not, or you're curious, see :ref:`Manual Setup `. +.. tip:: + + If you're using Encore, be sure to install your assets (e.g. ``npm install``) + and restart Encore. + Usage ----- You can now create custom Stimulus controllers inside of the ``assets/controllers.`` -directory. In fact, you should have an example controller there already: ``hello_controller.js``. +directory. In fact, you should have an example controller there already: ``hello_controller.js``: + +.. code-block:: javascript + + import { Controller } from '@hotwired/stimulus'; + + export default class extends Controller { + connect() { + this.element.textContent = 'Hello Stimulus! Edit me in assets/controllers/hello_controller.js'; + } + } Use the Twig functions from this bundle to activate your controllers: @@ -49,14 +65,98 @@ Use the Twig functions from this bundle to activate your controllers: ... -Your app will also activate any 3rd party controllers (installed by UX bundles) -mentioned in your ``assets/controllers.json`` file. +That's it! Whenever this element appears on the page, the ``hello`` controller +will activate. + +There's a *lot* more to learn about Stimulus. See the `Stimulus Documentation`_ +for all the goodies. + +.. _ux-packages: + +The UX Packages +~~~~~~~~~~~~~~~ + +Symfony provides a set of UX packages that add extra Stimulus controllers to solve +common problems. StimulusBundle activates any 3rd party Stimulus controllers +that are mentioned in your ``assets/controllers.json`` file. This file is updated +whenever you install a UX package. + +The official UX packages are: + +* `ux-autocomplete`_: Transform ``EntityType``, ``ChoiceType`` or *any* + ``