Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit 2aaad00

Browse files
almarchenkoalmarchenko
authored
Merge pull request #422 from magento/am_59999
Am 59999
2 parents 1c26d0e + bb7d9ee commit 2aaad00

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

‎guides/v2.1/ui_comp_guide/concepts/ui_comp_linking_concept.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
layout: default
3+
group: UI_Components_guide
4+
subgroup: concepts
5+
title: Linking properties of UI components
6+
menu_title: Linking properties of UI components
7+
menu_order: 14
8+
version: 2.1
9+
github_link: ui_comp_guide/concepts/ui_comp_linking_concept.md
10+
---
11+
12+
## {{page.menu_title}}
13+
{:.no_toc}
14+
15+
* TOC
16+
{:toc}
17+
18+
## Linking properties implementation
19+
20+
The following properties are used for linking observable properties and methods of UI components:
21+
22+
- `exports`
23+
- `imports`
24+
- `links`
25+
- `listens`
26+
27+
These properties are processed by the `initLinks()` method of the [`uiElement` class]({{page.baseurl}}/ui_comp_guide/concepts/ui_comp_uielement_concept.html) which is called at the moment of a component's instantiation.
28+
29+
Linking properties are set in [UI components configuration files]({{page.baseurl}}ui_comp_guide/concepts/ui_comp_config_flow_concept.html): XML, JS or PHP.
30+
31+
## List of linking properties
32+
33+
### `exports`
34+
35+
The `exports` property is used to notify some external entity that a property has changed. `exports`'s value is an object, composed of the following:
36+
37+
- `key`: name of the internal property or method that is tracked for changes.
38+
- `value`: name of the property or method that receives the notification. Can use [string templates](#string_templ).
39+
40+
Example of setting `exports` in a component's `.js` file:
41+
42+
{% highlight js%}
43+
{
44+
'exports': {
45+
'visible': '${ $.provider }:visibility'
46+
}
47+
}
48+
{% endhighlight js%}
49+
50+
Here `visible` is the `key`, `${ $.provider }:visibility` is the `value`. The value of the local `visible` property is assigned to the `visibility` property of the `provider` component. The latter is changed automatically if the value of `visible` changes.
51+
52+
Example of setting `exports` in a component's configuration `.xml` file:
53+
54+
{% highlight xml%}
55+
<argument name="data" xsi:type="array">
56+
<item name="config" xsi:type="array">
57+
<item name="exports" xsi:type="array">
58+
<item name="visible" xsi:type="string">sample_config.sample_provider:visibility</item>
59+
</item>
60+
</item>
61+
</argument>
62+
{% endhighlight xml%}
63+
64+
For an example of `exports` usage in Magento code see [`product_form.xml`, line 81]({{site.mage2100url}}/app/code/Magento/CatalogInventory/view/adminhtml/ui_component/product_form.xml#L81)
65+
66+
### `imports`
67+
The `imports` property is used for tracking changes of an external entity property. `imports`'s value is an object, composed of the following:
68+
69+
- `key`: name of the internal property or method that receives the notifications.
70+
- `value`: name of the property or method that is tracked for changes. Can use [string templates](#string_templ).
71+
72+
Example of using `imports` in a component's `.js` file:
73+
74+
{% highlight js%}
75+
{
76+
'imports': {
77+
'visible': '${ $.provider }:visibility'
78+
}
79+
}
80+
{% endhighlight js%}
81+
82+
Here the value of the `visibility` property of the `provider` component is assigned to the local `visible` property. The latter is automatically updated if `visibility` changes.
83+
84+
Example of using `imports` in a component's configuration `.xml` file:
85+
86+
{% highlight xml%}
87+
<argument name="data" xsi:type="array">
88+
<item name="config" xsi:type="array">
89+
<item name="imports" xsi:type="array">
90+
<item name="visible" xsi:type="string">sample_config.sample_provider:visibility</item>
91+
</item>
92+
</item>
93+
</argument>
94+
{% endhighlight xml%}
95+
96+
For an example of `imports` usage in Magento code see [`product_form.xml`, line 103]({{site.mage2100url}}/app/code/Magento/CatalogInventory/view/adminhtml/ui_component/product_form.xml#L103)
97+
98+
### `links`
99+
100+
The `links` property is used for cross tracking properties changes: both linked properties are tracked and changing of one results in changing the other. `links`'s value is an object, composed of the following:
101+
102+
- `key`: name of the internal property or method that sends and receives the notifications.
103+
- `value`: name of the property or method that sends and receives the notifications. Can use [string templates](#string_templ).
104+
105+
Example of using `links` in a component's `.js` file:
106+
107+
{% highlight js%}
108+
{
109+
'links': {
110+
'visible': '${ $.provider }:visibility'
111+
}
112+
}
113+
{% endhighlight js%}
114+
115+
Here the local `visible` property is linked with the `visibility` property of the provider component. Once any of them changes, the other is changed automatically.
116+
117+
Example of using `links` in a component's configuration `.xml` file:
118+
119+
{% highlight xml%}
120+
<argument name="data" xsi:type="array">
121+
<item name="config" xsi:type="array">
122+
<item name="links" xsi:type="array">
123+
<item name="visible" xsi:type="string">sample_config.sample_provider:visibility</item>
124+
</item>
125+
</item>
126+
</argument>
127+
{% endhighlight xml%}
128+
129+
For an example of `links` usage in Magento code see [`text.js`, line 19]({{site.mage2100url}}app/code/Magento/Ui/view/base/web/js/form/element/text.js#L19)
130+
131+
### `listens`
132+
The `listens` property is used to track the changes of a component's property. `listens`'s value is an object, composed of the following:
133+
134+
- `key`: name of the internal property which listens to the changes.
135+
- `value`: name of the property or method which is tracked for changes. Can use [string templates](#string_templ).
136+
137+
Example of using `listens` in a component's `.js` file :
138+
139+
{% highlight js%}
140+
{
141+
'listens': {
142+
'visible': '${ $.provider }:visibility'
143+
}
144+
}
145+
{% endhighlight js%}
146+
147+
Here the value of the local `visible` property is assigned to the `visibility` property of the `provider` component. The latter is changed automatically if the value of `visible` changes.
148+
149+
150+
Example of using `listens` in a component's configuration `.xml` file:
151+
152+
{% highlight xml%}
153+
<argument name="data" xsi:type="array">
154+
<item name="config" xsi:type="array">
155+
<item name="listens" xsi:type="array">
156+
<item name="visible" xsi:type="string">sample_config.sample_provider:visibility</item>
157+
</item>
158+
</item>
159+
</argument>
160+
{% endhighlight xml%}
161+
162+
For example of `listens` usage in Magento code see [`new_category_form.xml`, line 92]({{site.mage2100url}}app/code/Magento/Catalog/view/adminhtml/ui_component/new_category_form.xml#L92)
163+
164+
## Template strings usage {#string_templ}
165+
166+
The `value` options of linking properties can contain template strings in the `'${...}'` format. During component’s initialization, values in this format are processed as template strings using [ES6 templates](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Template_literals). In browsers that do not support ES6 templates, these values are processed as underscore templates.
167+
168+
So if we put a variable name in `'${...}'`, it is processed into a string representation of the variable’s value.
169+
170+
When working with UI components, we often need to use the string representation of a certain property of the UI component. To address a property of the UI component in the scope of this component, the `$.someProperty` syntax is used.
171+
172+
As a result, if the component's property is the variable for the template string, we get notation similar to the following:
173+
174+
'${ $.provider }'
175+
176+
We can also build complex templates strings using this syntax, as follows:
177+
178+
- Using variables from the other component:
179+
180+
```
181+
'${ $.provider }:${ $.dataScope }' // 'provider' is the full name of the other component
182+
```
183+
- Calling several functions in one string:
184+
185+
```
186+
'${ $.provider }:data.overload': 'overload reset validate'// we call 'overload', 'reset', 'validate'
187+
```
188+
189+
- Using inline conditions:
190+
191+
```
192+
'${ $.provider }:${ $.customScope ? $.customScope + "." : ""}data.validate': 'validate'
193+
```

0 commit comments

Comments
 (0)