Skip to content
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.

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

Document about alternative JS assets installation with npm packages #2617

Open
wants to merge 1 commit into
base: 2.x
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions src/Autocomplete/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-autocomplete package`_ can be used to install the JavaScript assets without requiring PHP.

Usage in a Form (without Ajax)
------------------------------

Expand Down Expand Up @@ -288,7 +292,7 @@ Passing Extra Options to the Ajax-powered Autocomplete

Autocomplete field options are **not preserved** when the field is rendered
on an Ajax call. So, features like exclude some options based on the current
form data are not possible by default.
form data are not possible by default.

To partially avoid this limitation, the ``extra_options`` option was added.

Expand All @@ -299,7 +303,7 @@ To partially avoid this limitation, the ``extra_options`` option was added.
can be passed as extra options.

Considering the following example, when the form type is rendered for the first
time, it will use the ``query_builder`` defined while adding a ``food`` field
time, it will use the ``query_builder`` defined while adding a ``food`` field
to the ``FoodForm``. However, when the Ajax is used to fetch the results, on
the consequent renders, the default ``query_builder`` will be used::

Expand All @@ -324,8 +328,8 @@ the consequent renders, the default ``query_builder`` will be used::
}
}

If some food can be consisted of other foods, we might want to exclude the
"root" food from the list of available foods. To achieve this, we can remove
If some food can be consisted of other foods, we might want to exclude the
"root" food from the list of available foods. To achieve this, we can remove
the ``query_builder`` option from the above example and pass the ``excluded_foods``
extra option to the ``FoodAutocompleteField``::

Expand Down Expand Up @@ -600,13 +604,13 @@ Passing Extra Options to the Autocompleter

The ability to pass extra options was added in Autocomplete 2.14.

If you need to pass extra options to the autocompleter, you can do so by
implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface``
If you need to pass extra options to the autocompleter, you can do so by
implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface``
interface.

.. tip::

If you want to know **why** you might need to use the ``extra_options``
If you want to know **why** you might need to use the ``extra_options``
feature, see :ref:`passing-extra-options-to-the-ajax-powered-autocomplete`.

.. code-block:: diff
Expand Down Expand Up @@ -757,3 +761,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
.. _`Tom Select Render Templates`: https://tom-select.js.org/docs/#render-templates
.. _`Tom Select Option Group`: https://tom-select.js.org/examples/optgroups/
.. _`Symfony Form`: https://symfony.com/doc/current/forms.html
.. _`@symfony/ux-autocomplete package`: https://www.npmjs.com/package/@symfony/ux-autocomplete
5 changes: 5 additions & 0 deletions src/Chartjs/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-chartjs package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -253,3 +257,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
.. _`zoom plugin documentation`: https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/integration.html
.. _`register Chart.js plugins globally`: https://www.chartjs.org/docs/latest/developers/plugins.html
.. _`Tooltip positioner`: https://www.chartjs.org/docs/latest/samples/tooltip/position.html
.. _`@symfony/ux-chartjs package`: https://www.npmjs.com/package/@symfony/ux-chartjs
5 changes: 5 additions & 0 deletions src/Cropperjs/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-cropperjs package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -149,3 +153,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`the Symfony UX initiative`: https://ux.symfony.com/
.. _`the Cropper.js options`: https://github.com/fengyuanchen/cropperjs/blob/main/README.md#options
.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
.. _`@symfony/ux-cropperjs package`: https://www.npmjs.com/package/@symfony/ux-cropperjs
5 changes: 5 additions & 0 deletions src/Dropzone/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-dropzone package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -155,3 +159,4 @@ https://symfony.com/doc/current/contributing/code/bc.html

.. _`the Symfony UX initiative`: https://ux.symfony.com/
.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
.. _`@symfony/ux-dropzone package`: https://www.npmjs.com/package/@symfony/ux-dropzone
9 changes: 7 additions & 2 deletions src/LazyImage/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-lazy-image package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -216,7 +220,7 @@ on the page and should be less than 2.5 seconds. It's part of the `Core Web Vita
and is used by Google to evaluate the user experience of a website, impacting
the Search ranking.

Using the Symfony UX LazyImage for your LCP image can be a good idea at first,
Using the Symfony UX LazyImage for your LCP image can be a good idea at first,
but in reality, it will lower the LCP score because:

- `The progressive loading (through blurhash) is not taken into account in the LCP calculation`_;
Expand All @@ -239,7 +243,7 @@ A solution is to not use the Stimulus controller for the LCP image but to use
width="200"
height="150"
/>

This way, the browser will display the BlurHash image as soon as possible, and
will load the high-definition image at the same time, without waiting for the
Stimulus controller to be loaded.
Expand All @@ -262,3 +266,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`Core Web Vitals`: https://web.dev/vitals/
.. _`The progressive loading (through blurhash) is not taken into account in the LCP calculation`: https://github.com/w3c/largest-contentful-paint/issues/71_
.. _`didn't preload the image`: https://symfony.com/doc/current/web_link.html
.. _`@symfony/ux-lazy-image package`: https://www.npmjs.com/package/@symfony/ux-lazy-image
7 changes: 6 additions & 1 deletion src/LiveComponent/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-live-component package`_ can be used to install the JavaScript assets without requiring PHP.

If your project is localized in different languages (either via the `locale route parameter`_
or by `setting the locale in the request`_) add the ``{_locale}`` attribute to
the UX Live Components route definition to keep the locale between re-renders:
Expand Down Expand Up @@ -3790,7 +3794,7 @@ uses Symfony's test client to render and make requests to your components::
// authenticate a user ($user is instance of UserInterface)
$testComponent->actingAs($user);

// set the '_locale' route parameter (if the component route is localized)
// set the '_locale' route parameter (if the component route is localized)
$testComponent->setRouteLocale('fr');

// customize the test client
Expand Down Expand Up @@ -3892,3 +3896,4 @@ promise. However, any internal implementation in the JavaScript files
.. _`locale route parameter`: https://symfony.com/doc/current/translation.html#the-locale-and-the-url
.. _`setting the locale in the request`: https://symfony.com/doc/current/translation.html#translation-locale
.. _`Stimulus action parameter`: https://stimulus.hotwired.dev/reference/actions#action-parameters
.. _`@symfony/ux-live-component package`: https://www.npmjs.com/package/@symfony/ux-live-component
18 changes: 5 additions & 13 deletions src/Map/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,6 @@ Install the bundle using Composer and Symfony Flex:

$ composer require symfony/ux-map

If you're using WebpackEncore, install your assets and restart Encore (not
needed if you're using AssetMapper):

.. code-block:: terminal

$ npm install --force
$ npm run watch

Comment on lines -19 to -26
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no assets for symfony/ux-map, so let's remove this confusing part.

Configuration
-------------

Expand Down Expand Up @@ -140,25 +132,25 @@ Remove elements from Map
~~~~~~~~~~~~~~~~~~~~~~~~

It is possible to remove elements like ``Marker``, ``Polygon`` and ``Polyline`` instances by using ``Map::remove*()`` methods::

// Add elements
$map->addMarker($marker = new Marker(/* ... */));
$map->addPolygon($polygon = new Polygon(/* ... */));
$map->addPolyline($polyline = new Polyline(/* ... */));

// And later, remove those elements
$map->removeMarker($marker);
$map->removePolygon($polygon);
$map->removePolyline($polyline);

If unfortunately you were unable to store an element instance, you can still remove them by passing the identifier string::

$map = new Map(/* ... */);
// Add elements
$map->addMarker(new Marker(id: 'my-marker', /* ... */));
$map->addPolygon(new Polygon(id: 'my-polygon', /* ... */));
$map->addPolyline(new Polyline(id: 'my-marker', /* ... */));

// And later, remove those elements
$map->removeMarker('my-marker');
$map->removePolygon('my-polygon');
Expand Down
19 changes: 19 additions & 0 deletions src/Map/src/Bridge/Google/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,25 @@

[Google Maps](https://developers.google.com/maps/documentation/javascript/overview) integration for Symfony UX Map.

## Installation

Install the bundle using Composer and Symfony Flex:

```shell
composer require symfony/ux-google-map
```

If you're using WebpackEncore, install your assets and restart Encore (not
needed if you're using AssetMapper):

```shell
npm install --force
npm run watch
```

> [!NOTE]
> Alternatively, [@symfony/ux-google-map package](https://www.npmjs.com/package/@symfony/ux-google-map) can be used to install the JavaScript assets without requiring PHP.

## DSN example

```dotenv
Expand Down
19 changes: 19 additions & 0 deletions src/Map/src/Bridge/Leaflet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,25 @@

[Leaflet](https://leafletjs.com/) integration for Symfony UX Map.

## Installation

Install the bundle using Composer and Symfony Flex:

```shell
composer require symfony/ux-leaflet-map
```

If you're using WebpackEncore, install your assets and restart Encore (not
needed if you're using AssetMapper):

```shell
npm install --force
npm run watch
```

> [!NOTE]
> Alternatively, [@symfony/ux-leaflet-map package](https://www.npmjs.com/package/@symfony/ux-leaflet-map) can be used to install the JavaScript assets without requiring PHP.

## DSN example

```dotenv
Expand Down
5 changes: 5 additions & 0 deletions src/Notify/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-notify package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -154,3 +158,4 @@ https://symfony.com/doc/current/contributing/code/bc.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
.. _`@symfony/ux-notify package`: https://www.npmjs.com/package/@symfony/ux-notify
13 changes: 9 additions & 4 deletions src/React/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@ Next, install a package to help React:
$ npm install -D @babel/preset-react --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-react package`_ can be used to install the JavaScript assets without requiring PHP.

That's it! Any files inside ``assets/react/controllers/`` can now be rendered as
React components.

Expand Down Expand Up @@ -99,21 +103,21 @@ Permanent components
The ability to mark a component ``permanent`` was added in UX React 2.21.

The controller responsible to render the React components can be configured
to keep the React component mounted when the root element is removed from
to keep the React component mounted when the root element is removed from
the DOM, using the ``permanent`` option.

This is particularly useful when the root element of a component is moved around
in the DOM or is removed and immediately re-added to the DOM (e.g. when using
in the DOM or is removed and immediately re-added to the DOM (e.g. when using
`Turbo`_ and its `data-turbo-permanent` attribute).

.. code-block:: html+twig

{# templates/home.html.twig #}
{% extends 'base.html.twig' %}

{# The React component will stay mounted if the div is moved in the DOM #}
<div {{ react_component('Hello', {fullName: 'Fabien'}, {permanent: true}) }}>
Loading...
Loading...
</div>

.. _using-with-asset-mapper:
Expand Down Expand Up @@ -156,3 +160,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`Symfony UX initiative`: https://ux.symfony.com/
.. _`Symfony UX React demo`: https://ux.symfony.com/react
.. _`Turbo`: https://turbo.hotwire.dev/
.. _`@symfony/ux-react package`: https://www.npmjs.com/package/@symfony/ux-react
5 changes: 5 additions & 0 deletions src/StimulusBundle/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ necessary files. If not, or you're curious, see :ref:`Manual Setup <manual-insta
If you're using Encore, be sure to install your assets (e.g. ``npm install``)
and restart Encore.

.. note::

Alternatively, the `@symfony/stimulus-bundle package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -533,3 +537,4 @@ it will normalize it:
.. _`sensiolabs/typescript-bundle`: https://github.com/sensiolabs/AssetMapperTypeScriptBundle
.. _`Stimulus plugin`: https://plugins.jetbrains.com/plugin/24562-stimulus
.. _`official UX packages`: https://ux.symfony.com/packages
.. _`@symfony/stimulus-bundle package`: https://www.npmjs.com/package/@symfony/stimulus-bundle
5 changes: 5 additions & 0 deletions src/Svelte/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ Install the bundle using Composer and Symfony Flex:
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-svelte package`_ can be used to install the JavaScript assets without requiring PHP.

The Flex recipe will automatically set things up for you, like adding
``.enableSvelte()`` to your ``webpack.config.js`` file and adding code
to load your Svelte components inside ``assets/app.js``.
Expand Down Expand Up @@ -150,3 +154,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`Svelte`: https://svelte.dev/
.. _`the Symfony UX initiative`: https://ux.symfony.com/
.. _the Svelte 4 migration guide: https://svelte.dev/docs/v4-migration-guide#browser-conditions-for-bundlers
.. _`@symfony/ux-svelte package`: https://www.npmjs.com/package/@symfony/ux-svelte
5 changes: 5 additions & 0 deletions src/Swup/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-swup package`_ can be used to install the JavaScript assets without requiring PHP.

Usage
-----

Expand Down Expand Up @@ -202,3 +206,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`StimulusBundle`: https://symfony.com/bundles/StimulusBundle/current/index.html
.. _`Swup Options`: https://swup.js.org/options
.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
.. _`@symfony/ux-swup package`: https://www.npmjs.com/package/@symfony/ux-swup
5 changes: 5 additions & 0 deletions src/TogglePassword/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ needed if you're using AssetMapper):
$ npm install --force
$ npm run watch

.. note::

Alternatively, the `@symfony/ux-toggle-password package`_ can be used to install the JavaScript assets without requiring PHP.

Usage with Symfony Forms
------------------------

Expand Down Expand Up @@ -301,3 +305,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
.. _`the Symfony UX initiative`: https://ux.symfony.com/
.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
.. _Heroicons: https://heroicons.com/
.. _`@symfony/ux-toggle-password package`: https://www.npmjs.com/package/@symfony/ux-toggle-password
Loading
Loading