1. What is UI components in Magento 2?

In Magento 2, UI component is an association of:

  1. XML declaration that specifies the component’s configuration settings and inner structure.
  2. JavaScript class inherited from one of the Magento JavaScript framework UI components base classes (such as UIElement, UIClass or UICollection).
  3. Related template(s)

To deliver a simple and flexible UI, we use the responsive UI components of Magento, which renders the page supporting the interaction between Javascript and server. Sometimes, during a project or extension development, interaction between 2 UI components is required. In this article, we will explain how to link data between UI components in Magento 2.

Magento 2 offers three types of property links:

  • Exports
  • Imports
  • Links

These properties are processed by the initLinks() method of the uiElement class which is called at the moment of a component’s instantiation.

2. Imports property in UI component

The definition of Imports property

The Imports property is used for tracking changes of an external component property. The value of the import is an object which includes two elements:

  • key: name of the internal property or method that receives the value.
  • value: name of the property or method is tracked for changes.

The example of Imports in a component file

Example of using imports in a component’s .js file:

{
  "provider": "<data>",
  ...
  "defaults": {
     ...
    "imports": {
      "attribute_set_id": "${$.provider}:data.product.attribute_set_id"
    },
  ...
  }
}

${$.provider} is data provider for the import. ${} is the syntax, $.provider is the identification for the destination component. $ stands for the current component, .provider means property named provider of the component.

You can also define a custom provider in the same field/fieldset and use it for import. Example:

{
  "defaults": {
     …
    "provider1": "magenest_listing.magenest_listing_data_source”,
    "imports": {
      "attribute_set_id": "${$.provider1}:data.product.attribute_set_id"
    },
  ...
  }
}

Provider can be a name, resource, or index.

When the Element class initializes, it will process the link that was declared in imports. In the example above, it will return the value to attribute_set_id property. Magento will parse the $.provider and should obtain a value. Since the attribute_set_id property is in the imports property, it will be passed to the setLinks() method in uiElement.initLinks(). The setLinks() method is in Magento/Ui/view/base/web/js/lib/core/element/links.js . There, it loops over all properties (only attribute_set_id in this example) in the object that was passed in (imports in this case). 

On those properties, it will attempt to transfer data from one component to the other. With the transfer() function, the registry is searched for the component that is the "owner", in the case of an import. This component is the one that currently "owns" or has the data and would be the $.provider in the above example. If the component is found, it will then proceed to link the data with the setLink() function. 

There are two things of note in that method:

  • It sets an event listener on the property.
  • It will immediately transfer the data if the applicable flag has been sent.

The data is then set on a component that had the imports: {} property. 

Example of using imports in a component’s configuration .xml file:

<argument name="data" xsi:type="array">
    <item name="config" xsi:type="array">
    ...
        <item name="childDefaults" xsi:type="array">
            <item name="provider" xsi:type="string">magenest_popup_log_listing.magenest_popup_log_listing.listing_top.listing_filters</item>
            <item name="imports" xsi:type="array">
                <item name="visible" xsi:type="string">magenest_popup_log_listing.magenest_popup_log_listing.magenest_popup_log_columns.${ $.index }:visible</item>
                </item>
        	</item>
    </item>
</argument>

3. Exports property in UI component

The definition of Exports property

Exports property is the inverse of imports. It is used to copy a local value to some external entity.  If the external entity property is anything but a function, it will be set to the value of the local property. If the external property is a function, it will be called with the local properties value as an argument. The external entity will also be updated whenever the local property changes. Exports’s value is an object, composed of the following: 

  • key: name of the internal property or method that is tracked for changes.
  • value: name of the property or method that receives the value

The example of Exports in a component file

Example of setting exports in a component’s .js file: 

{
  "defaults": {
    ...
    "exports": {
      "attribute_set_id": "${$.provider}:data.new-variations-attribute-set-id"
    }
  ...
  }
}

In this example, the attribute_set_id is the key, ${$.provider}:data.new-variations-attribute-set-id is the value. The value of the local attribute_set_id property is assigned to the new-variations-attribute-set-id property of the provider component. The latter is changed automatically if the value of the attribute_set_id changes if the local attribute_set_id property is observable.
In summary, instead of taking data from one component and assigning it to itself, exports sends its own data to another component. As a result, nearly everything is the opposite.

4. Links property in UI Component

The definition of Links property

Finally, 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:

  • key: name of the internal property or method that sends and receives the notifications.
  • value: name of the property or method that sends and receives the value

The example of Links in a component file

Example of using links in a component’s .js file:

{
  "defaults": {
    ...
    "links": {
      "value": "checkoutProvider:shippingAddress.firstname"
    }
   ...
  }
}

When you use a links value, you’re both importing and exporting the properties from the specified registry entry.

Note: by default, links are not a way to connect two other modules. In other words, ComponentC cannot link ComponentA to ComponentB. It is a method of bi-directionally syncing one component with another.

5. Summary

Linking (imports, exports, and links) can almost always facilitate functions assigned to those properties as well. The linking provides values that are available in KnockoutJS scope and can be manipulated as you would any other property. And, to reiterate clearly: remember that the imports, exports, and links object's keys always refer to properties of the current component (the one in which those properties were declared), while the value pertains to the name and properties of the remote component.

In conclusion, Magento uses this linking functionality to connect different components with each other and it is a way that we can access, provide or sync data with other components.