Skip to content

Commit 823b87c

Browse files
KocalKocal
committed
minor #2617 Document about alternative JS assets installation with npm packages (Kocal)
This PR was merged into the 2.x branch. Discussion ---------- Document about alternative JS assets installation with npm packages | Q | A | ------------- | --- | Bug fix? | no | New feature? | no <!-- please update src/**/CHANGELOG.md files --> | Issues | Fix #2575 <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead --> | License | MIT <!-- Replace this notice by a description of your feature/bugfix. This will help reviewers and should be a good start for the documentation. Additionally (see https://symfony.com/releases): - Always add tests and ensure they pass. - For new features, provide some code snippets to help understand usage. - Features and deprecations must be submitted against branch main. - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry - Never break backward compatibility (see https://symfony.com/bc). --> Follow #2616 Commits ------- 9131a71 Document about alternative JS assets installation with npm packages
2 parents 0287b2a + 9131a71 commit 823b87c

File tree

38 files changed

+333
-91
lines changed

38 files changed

+333
-91
lines changed

‎src/Autocomplete/assets/README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# @symfony/ux-autocomplete
22

3-
Javascript-powered auto-completion functionality for your Symfony forms!
3+
JavaScript assets of the [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) PHP package.
44

5-
**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) in a Symfony application with Flex enabled.
5+
## Installation
66

7-
If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) PHP package version.**
7+
This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
8+
9+
We **strongly recommend not installing this package directly**, but instead install the PHP package [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
10+
11+
If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) PHP package version:
12+
```shell
13+
composer require symfony/ux-autocomplete:2.23.0
14+
npm add @symfony/ux-autocomplete@2.23.0
15+
```
816

917
## Resources
1018

‎src/Autocomplete/doc/index.rst

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ needed if you're using AssetMapper):
3030
$ npm install --force
3131
$ npm run watch
3232
33+
.. note::
34+
35+
For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-autocomplete npm package`_
36+
3337
Usage in a Form (without Ajax)
3438
------------------------------
3539

@@ -288,7 +292,7 @@ Passing Extra Options to the Ajax-powered Autocomplete
288292

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

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

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

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

@@ -324,8 +328,8 @@ the consequent renders, the default ``query_builder`` will be used::
324328
}
325329
}
326330

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

@@ -600,13 +604,13 @@ Passing Extra Options to the Autocompleter
600604

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

603-
If you need to pass extra options to the autocompleter, you can do so by
604-
implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface``
607+
If you need to pass extra options to the autocompleter, you can do so by
608+
implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface``
605609
interface.
606610

607611
.. tip::
608612

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

612616
.. code-block:: diff
@@ -757,3 +761,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
757761
.. _`Tom Select Render Templates`: https://tom-select.js.org/docs/#render-templates
758762
.. _`Tom Select Option Group`: https://tom-select.js.org/examples/optgroups/
759763
.. _`Symfony Form`: https://symfony.com/doc/current/forms.html
764+
.. _`@symfony/ux-autocomplete npm package`: https://www.npmjs.com/package/@symfony/ux-autocomplete

‎src/Chartjs/assets/README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# @symfony/ux-chartjs
22

3-
Chart.js integration for Symfony.
3+
JavaScript assets of the [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) PHP package.
44

5-
**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) in a Symfony application with Flex enabled.
5+
## Installation
66

7-
If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) PHP package version.**
7+
This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
8+
9+
We **strongly recommend not installing this package directly**, but instead install the PHP package [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
10+
11+
If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) PHP package version:
12+
```shell
13+
composer require symfony/ux-chartjs:2.23.0
14+
npm add @symfony/ux-chartjs@2.23.0
15+
```
816

917
## Resources
1018

‎src/Chartjs/doc/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ needed if you're using AssetMapper):
2222
$ npm install --force
2323
$ npm run watch
2424
25+
.. note::
26+
27+
For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-chartjs npm package`_
28+
2529
Usage
2630
-----
2731

@@ -253,3 +257,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
253257
.. _`zoom plugin documentation`: https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/integration.html
254258
.. _`register Chart.js plugins globally`: https://www.chartjs.org/docs/latest/developers/plugins.html
255259
.. _`Tooltip positioner`: https://www.chartjs.org/docs/latest/samples/tooltip/position.html
260+
.. _`@symfony/ux-chartjs npm package`: https://www.npmjs.com/package/@symfony/ux-chartjs

‎src/Cropperjs/assets/README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# @symfony/ux-cropperjs
22

3-
Cropper.js integration for Symfony.
3+
JavaScript assets of the [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) PHP package.
44

5-
**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) in a Symfony application with Flex enabled.
5+
## Installation
66

7-
If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) PHP package version.**
7+
This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
8+
9+
We **strongly recommend not installing this package directly**, but instead install the PHP package [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
10+
11+
If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) PHP package version:
12+
```shell
13+
composer require symfony/ux-cropperjs:2.23.0
14+
npm add @symfony/ux-cropperjs@2.23.0
15+
```
816

917
## Resources
1018

‎src/Cropperjs/doc/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ needed if you're using AssetMapper):
2626
$ npm install --force
2727
$ npm run watch
2828
29+
.. note::
30+
31+
For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-cropperjs npm package`_
32+
2933
Usage
3034
-----
3135

@@ -149,3 +153,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
149153
.. _`the Symfony UX initiative`: https://ux.symfony.com/
150154
.. _`the Cropper.js options`: https://github.com/fengyuanchen/cropperjs/blob/main/README.md#options
151155
.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
156+
.. _`@symfony/ux-cropperjs npm package`: https://www.npmjs.com/package/@symfony/ux-cropperjs

‎src/Dropzone/assets/README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# @symfony/ux-dropzone
22

3-
File input dropzones for Symfony Forms.
3+
JavaScript assets of the [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) PHP package.
44

5-
**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) in a Symfony application with Flex enabled.
5+
## Installation
66

7-
If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) PHP package version.**
7+
This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
8+
9+
We **strongly recommend not installing this package directly**, but instead install the PHP package [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
10+
11+
If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) PHP package version:
12+
```shell
13+
composer require symfony/ux-dropzone:2.23.0
14+
npm add @symfony/ux-dropzone@2.23.0
15+
```
816

917
## Resources
1018

‎src/Dropzone/doc/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@ needed if you're using AssetMapper):
2828
$ npm install --force
2929
$ npm run watch
3030
31+
.. note::
32+
33+
For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-dropzone npm package`_
34+
3135
Usage
3236
-----
3337

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

156160
.. _`the Symfony UX initiative`: https://ux.symfony.com/
157161
.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
162+
.. _`@symfony/ux-dropzone npm package`: https://www.npmjs.com/package/@symfony/ux-dropzone

‎src/LazyImage/assets/README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# @symfony/ux-lazy-image
22

3-
Lazy image loader and utilities for Symfony.
3+
JavaScript assets of the [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) PHP package.
44

5-
**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) in a Symfony application with Flex enabled.
5+
## Installation
66

7-
If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) PHP package version.**
7+
This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
8+
9+
We **strongly recommend not installing this package directly**, but instead install the PHP package [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
10+
11+
If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) PHP package version:
12+
```shell
13+
composer require symfony/ux-lazy-image:2.23.0
14+
npm add @symfony/ux-lazy-image@2.23.0
15+
```
816

917
## Resources
1018

‎src/LazyImage/doc/index.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ needed if you're using AssetMapper):
3636
$ npm install --force
3737
$ npm run watch
3838
39+
.. note::
40+
41+
For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-lazy-image npm package`_
42+
3943
Usage
4044
-----
4145

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

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

222226
- `The progressive loading (through blurhash) is not taken into account in the LCP calculation`_;
@@ -239,7 +243,7 @@ A solution is to not use the Stimulus controller for the LCP image but to use
239243
width="200"
240244
height="150"
241245
/>
242-
246+
243247
This way, the browser will display the BlurHash image as soon as possible, and
244248
will load the high-definition image at the same time, without waiting for the
245249
Stimulus controller to be loaded.
@@ -262,3 +266,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
262266
.. _`Core Web Vitals`: https://web.dev/vitals/
263267
.. _`The progressive loading (through blurhash) is not taken into account in the LCP calculation`: https://github.com/w3c/largest-contentful-paint/issues/71_
264268
.. _`didn't preload the image`: https://symfony.com/doc/current/web_link.html
269+
.. _`@symfony/ux-lazy-image npm package`: https://www.npmjs.com/package/@symfony/ux-lazy-image

0 commit comments

Comments
 (0)