You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
minor #2072 [Cookbook] English / doc / code corrections (smnandre)
This PR was squashed before being merged into the 2.x branch.
Discussion
----------
[Cookbook] English / doc / code corrections
One commit per "category"
`@WebMamba` I don't get the Stimulus button example... how would it work ?
Commits
-------
85426fa [Cookbook] English / doc / code corrections
description: Rules and pattern to work with components
2
+
title: Component Architecture
3
+
description: Rules and patterns for working with components
4
4
image: images/cookbook/component-architecture.png
5
5
tags:
6
6
- JavaScript
@@ -11,25 +11,25 @@ published_at: '2024-08-02'
11
11
12
12
## Introduction
13
13
14
-
In Symfony UX exist two packages: [TwigComponents](https://symfony.com/bundles/ux-twig-component/current/index.html) and [LiveComponent](https://symfony.com/bundles/ux-live-component/current/index.html).
15
-
Those two packages allow you to create reusable components in your Symfony application.
16
-
But the component architecture is not exclusive to Symfony, it's a design pattern that can be applied to any programming language or framework.
17
-
And the Javascript world already implements this architecture for long time, on many different frameworks like React, Vue, or Svelte.
18
-
So, a set of rules and patterns has already be defined to work with components. This is why Symfony UX tries to be as close as possible to those rules.
19
-
So, let's see what those rules are!
14
+
In Symfony UX, there are two packages: [TwigComponents](https://symfony.com/bundles/ux-twig-component/current/index.html) and [LiveComponent](https://symfony.com/bundles/ux-live-component/current/index.html).
15
+
These packages allow you to create reusable components in your Symfony application.
16
+
However, component architecture is not exclusive to Symfony; it's a design pattern that can be applied to any programming language or framework.
17
+
The JavaScript world has implemented this architecture for a long time, across many frameworks like React, Vue, or Svelte.
18
+
A set of rules and patterns has already been defined for working with components. This is why Symfony UX tries to adhere closely to these rules.
19
+
Let's explore what these rules are!
20
20
21
21
## 4 Rules
22
22
23
23
### Composition
24
24
25
-
A page is no longer just a page, but rather a collection of small, reusable components.
26
-
These components can be assembled to form a page. For example, there could be a component for the title and another for the training list.
27
-
The training list component could even be composed of smaller components, such as a training card component.
28
-
The goal is to create the most atomic, and reusable components possible.
25
+
A page is no longer just a page but rather a collection of small, reusable components.
26
+
These components can be assembled to form a page. For example, there could be a component for the title and another for the training list.
27
+
The training list component could even be composed of smaller components, such as a training card component.
28
+
The goal is to create the most atomic and reusable components possible.
29
29
30
-
#### How does it work into Symfony?
30
+
***How does it work in Symfony?***
31
31
32
-
In Symfony you can have a component Alertfor example with the following template:
32
+
In Symfony, you can have an `Alert` component, for example, with the following template:
33
33
34
34
```twig
35
35
<div class="alert alert-{{ type }}">
@@ -38,8 +38,8 @@ In Symfony you can have a component Alert for example with the following templat
38
38
</div>
39
39
```
40
40
41
-
So here you can see we have an alert component that his himself use an Icon component.
42
-
Or you can make composition with the following syntax:
41
+
So here you can see we have an `Alert` component that itself uses an Icon component.
42
+
Or you can compose with the following syntax:
43
43
44
44
```twig
45
45
<twig:Card>
@@ -50,30 +50,29 @@ Or you can make composition with the following syntax:
50
50
</twig:Card>
51
51
```
52
52
53
-
So here we have a Card component, and we give to the content of this component two other components.
53
+
So here we have a `Card` component, and we provide the content of this component with two other components.
54
54
55
55
### Independence
56
56
57
-
This is a really important rule, and not obvious. But your component should live on his own context,
58
-
it should not be aware of the rest of the page. You should be able to take a component into a page, from another and it should work exactly the same.
57
+
This is a really important rule and not an obvious one. Your component should live in its own context; it
58
+
should not be aware of the rest of the page. You should be able to take a component from one page to another, and it should work exactly the same.
59
59
This rule makes your component truly reusable.
60
60
61
-
***How does it work into Symfony?***
61
+
***How does it work in Symfony?***
62
62
63
-
Symfony keeps the context of the page into the context of your component. So this your own responsibility to follow those rules.
64
-
But notice that if there are conflicts between a variable from the context page and your component, your component context overrides the page context.
63
+
Symfony keeps the context of the page within the context of your component. So it is your own responsibility to follow these rules.
64
+
Note that if there are conflicts between a variable from the context page and your component, your component context overrides the page context.
65
65
66
66
### Props
67
67
68
-
Our component must remain independent, but we can customize it props.
69
-
Let's take the example of a button component. You have your component that look on every page the same,
70
-
the only change is the label. What you can do is to declare a prop `label` into your button component.
71
-
And so now when you want to use your button component, you can pass the label you want as props. The component gonna take
72
-
this props at his initialization and keep it all his life long.
68
+
Our component must remain independent, but we can customize its props.
69
+
For example, consider a button component. You want your component to look the same on every page, with the only change being the label.
70
+
To do this, you can declare a `label` prop in your button component.
71
+
When you use your button component, you can pass the label you want as a prop. The component will take this prop at initialization and keep it throughout its lifecycle.
73
72
74
-
***How does it work into Symfony?***
73
+
***How does it work in Symfony?***
75
74
76
-
Let's take the example of the Alert component an [anonymous component](https://symfony.com/bundles/ux-twig-component/current/index.html#anonymous-components).
75
+
Let's take the example of the `Alert` component as an [anonymous component](https://symfony.com/bundles/ux-twig-component/current/index.html#anonymous-components).
77
76
We have the following template:
78
77
79
78
```twig
@@ -85,16 +84,16 @@ We have the following template:
85
84
</div>
86
85
```
87
86
88
-
Just like that we define three props for our Alert component. And know we can use like this:
87
+
Just like that, we define three props for our `Alert` component. We can now use it like this:
89
88
90
89
```twig
91
90
<twig:Alert type="success" icon="check" message="Your account has been created." />
92
91
```
93
92
94
-
If your component anonymous but a class component, you can simply define props
95
-
by adding property to your class.
93
+
If your component is not anonymous but a class component, you can define props by adding properties to your class.
96
94
97
95
```php
96
+
#[AsTwigComponent]
98
97
class Alert
99
98
{
100
99
public string $type;
@@ -103,35 +102,32 @@ class Alert
103
102
}
104
103
```
105
104
106
-
There are something really important to notice with props. It's your props
107
-
should only go into one direction from the parent to child. But your props should never
108
-
go up. **If your child need to change something in the parent, you should use events**.
105
+
There is something important to note with props: They should only flow in one direction, from parent to child. Props should never go up. **If your child needs to change something in the parent, you should use events.**
109
106
110
107
### State
111
108
112
-
A state is pretty much like a prop but the main difference is a state can
109
+
A state is pretty much like a prop, but the main difference is that a state can
113
110
change during the life of the component. Let's take the example of a button component.
114
-
You can have a state `loading` that can be `true` or `false`. When the button is clicked
115
-
the state `loading` can be set to `true` and the button can display a loader instead of the label.
116
-
And when the loading is done, the state `loading` can be set to `false` and the button can display the label again.
111
+
You can have a `loading` state that can be `true` or `false`. When the button is clicked
112
+
the `loading`state can be set to `true`, and the button can display a loader instead of the label.
113
+
When the loading is done, the `loading`state can be set to `false`, and the button can display the label again.
117
114
118
-
***How does it work into Symfony?***
115
+
***How does it work in Symfony?***
119
116
120
-
In Symfony you have two different approaches to handle state. The first one is to use stimulus directly
121
-
in to your component. What we recommend to do is to set a controller stimulus at the root of your component.
117
+
In Symfony, you have two different approaches to handle state. The first is to use Stimulus directly in your component. We recommend setting a Stimulus controller at the root of your component.
0 commit comments