Skip to content

Commit 2e83f3c

Browse files
jmschejmsche
committed
Move ux bundle docs to a separate file in frontend docs
1 parent 25c0e36 commit 2e83f3c

File tree

2 files changed

+123
-115
lines changed

2 files changed

+123
-115
lines changed

‎bundles/best_practices.rst

Lines changed: 0 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -546,121 +546,6 @@ Beware that templates use a simplified version of the logical path shown above.
546546
For example, an ``index.html.twig`` template located in the ``templates/Default/``
547547
directory of the AcmeBlogBundle, is referenced as ``@AcmeBlog/Default/index.html.twig``.
548548

549-
Specifics for a UX Bundle
550-
-------------------------
551-
552-
Here are a few tricks to make your bundle install as a UX bundle.
553-
554-
composer.json file
555-
~~~~~~~~~~~~~~~~~~
556-
557-
Your ``composer.json`` file must have the ``symfony-ux`` keyword:
558-
559-
.. code-block:: json
560-
561-
{
562-
"keywords": ["symfony-ux"]
563-
}
564-
565-
Assets location
566-
~~~~~~~~~~~~~~~
567-
568-
Your assets must be located in one of the following directories, with a ``package.json`` file so Flex can handle it
569-
during install/update:
570-
571-
* ``/assets`` (recommended)
572-
* ``/Resources/assets``
573-
* ``/src/Resources/assets``
574-
575-
package.json file
576-
~~~~~~~~~~~~~~~~~
577-
578-
Your ``package.json`` file must contain a ``symfony`` config with controllers defined, and also add required packages
579-
to the ``peerDependencies``:
580-
581-
.. code-block:: json
582-
583-
{
584-
"name": "@acme/feature",
585-
"version": "1.0.0",
586-
"symfony": {
587-
"controllers": {
588-
"slug": {
589-
"main": "dist/controller.js",
590-
"webpackMode": "eager",
591-
"fetch": "eager",
592-
"enabled": true,
593-
"autoimport": {
594-
"dist/bootstrap4-theme.css": false,
595-
"dist/bootstrap5-theme.css": true
596-
}
597-
}
598-
}
599-
},
600-
"peerDependencies": {
601-
"@hotwired/stimulus": "^3.0.0",
602-
"slugify": "^1.6.5"
603-
}
604-
}
605-
606-
In this case, the file located at ``[assets directory]/dist/controller.js`` will be exposed.
607-
608-
.. tip::
609-
610-
You can either write raw JS in this ``dist/controller.js`` file, or you can e.g. write your controller with
611-
TypeScript and transpile it to JavaScript.
612-
613-
Here is an example to do so:
614-
615-
1. Add the following to your ``package.json`` file:
616-
617-
.. code-block:: json
618-
619-
{
620-
"scripts": {
621-
"build": "babel src --extensions .ts -d dist"
622-
},
623-
"devDependencies": {
624-
"@babel/cli": "^7.20.7",
625-
"@babel/core": "^7.20.12",
626-
"@babel/plugin-proposal-class-properties": "^7.18.6",
627-
"@babel/preset-env": "^7.20.2",
628-
"@babel/preset-typescript": "^7.18.6",
629-
"@hotwired/stimulus": "^3.2.1",
630-
"typescript": "^4.9.5"
631-
}
632-
}
633-
634-
2. Run either ``npm install`` or ``yarn install`` to install the new dependencies.
635-
636-
3. Write your Stimulus controller with TypeScript in ``src/controller.ts``.
637-
638-
4. Run ``npm run build`` or ``yarn run build`` to transpile your TypeScript controller into JavaScript.
639-
640-
To use your controller in a template (e.g. one defined in your bundle) you can use it like this:
641-
642-
.. code-block:: html+twig
643-
644-
<div
645-
{{ stimulus_controller('acme/feature/slug', { modal: 'my-value' }) }}
646-
{#
647-
will render:
648-
data-controller="acme--feature--slug"
649-
data-acme--feature--slug-modal-value="my-value"
650-
#}
651-
>
652-
...
653-
</div>
654-
655-
Don't forget to add ``symfony/webpack-encore-bundle:^1.12`` as a composer dependency to use
656-
Twig ``stimulus_*`` functions.
657-
658-
.. tip::
659-
660-
Controller Naming: In this example, the ``name`` of the PHP package is ``acme/feature`` and the name
661-
of the controller in ``package.json`` is ``slug``. So, the full controller name for Stimulus will be
662-
``acme--feature--slug``, though with the ``stimulus_controller()`` function, you can use ``acme/feature/slug``.
663-
664549
Learn more
665550
----------
666551

‎frontend/create_ux_bundle.rst

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. index::
2+
single: Create a UX bundle
3+
4+
Create a UX bundle
5+
==================
6+
7+
.. tip::
8+
9+
Before reading this, you may want to have a look at
10+
:doc:`Best Practices for Reusable Bundles </bundles/best_practices>`.
11+
12+
Here are a few tricks to make your bundle install as a UX bundle.
13+
14+
composer.json file
15+
------------------
16+
17+
Your ``composer.json`` file must have the ``symfony-ux`` keyword:
18+
19+
.. code-block:: json
20+
21+
{
22+
"keywords": ["symfony-ux"]
23+
}
24+
25+
Assets location
26+
---------------
27+
28+
Your assets must be located in one of the following directories, with a ``package.json`` file so Flex can handle it
29+
during install/update:
30+
31+
* ``/assets`` (recommended)
32+
* ``/Resources/assets``
33+
* ``/src/Resources/assets``
34+
35+
package.json file
36+
-----------------
37+
38+
Your ``package.json`` file must contain a ``symfony`` config with controllers defined, and also add required packages
39+
to the ``peerDependencies``:
40+
41+
.. code-block:: json
42+
43+
{
44+
"name": "@acme/feature",
45+
"version": "1.0.0",
46+
"symfony": {
47+
"controllers": {
48+
"slug": {
49+
"main": "dist/controller.js",
50+
"webpackMode": "eager",
51+
"fetch": "eager",
52+
"enabled": true,
53+
"autoimport": {
54+
"dist/bootstrap4-theme.css": false,
55+
"dist/bootstrap5-theme.css": true
56+
}
57+
}
58+
}
59+
},
60+
"peerDependencies": {
61+
"@hotwired/stimulus": "^3.0.0",
62+
"slugify": "^1.6.5"
63+
}
64+
}
65+
66+
In this case, the file located at ``[assets directory]/dist/controller.js`` will be exposed.
67+
68+
.. tip::
69+
70+
You can either write raw JS in this ``dist/controller.js`` file, or you can e.g. write your controller with
71+
TypeScript and transpile it to JavaScript.
72+
73+
Here is an example to do so:
74+
75+
1. Add the following to your ``package.json`` file:
76+
77+
.. code-block:: json
78+
79+
{
80+
"scripts": {
81+
"build": "babel src --extensions .ts -d dist"
82+
},
83+
"devDependencies": {
84+
"@babel/cli": "^7.20.7",
85+
"@babel/core": "^7.20.12",
86+
"@babel/plugin-proposal-class-properties": "^7.18.6",
87+
"@babel/preset-env": "^7.20.2",
88+
"@babel/preset-typescript": "^7.18.6",
89+
"@hotwired/stimulus": "^3.2.1",
90+
"typescript": "^4.9.5"
91+
}
92+
}
93+
94+
2. Run either ``npm install`` or ``yarn install`` to install the new dependencies.
95+
96+
3. Write your Stimulus controller with TypeScript in ``src/controller.ts``.
97+
98+
4. Run ``npm run build`` or ``yarn run build`` to transpile your TypeScript controller into JavaScript.
99+
100+
To use your controller in a template (e.g. one defined in your bundle) you can use it like this:
101+
102+
.. code-block:: html+twig
103+
104+
<div
105+
{{ stimulus_controller('acme/feature/slug', { modal: 'my-value' }) }}
106+
{#
107+
will render:
108+
data-controller="acme--feature--slug"
109+
data-acme--feature--slug-modal-value="my-value"
110+
#}
111+
>
112+
...
113+
</div>
114+
115+
Don't forget to add ``symfony/webpack-encore-bundle:^1.12`` as a composer dependency to use
116+
Twig ``stimulus_*`` functions.
117+
118+
.. tip::
119+
120+
Controller Naming: In this example, the ``name`` of the PHP package is ``acme/feature`` and the name
121+
of the controller in ``package.json`` is ``slug``. So, the full controller name for Stimulus will be
122+
``acme--feature--slug``, though with the ``stimulus_controller()`` function, you can use ``acme/feature/slug``.
123+

0 commit comments

Comments
 (0)