About XML сonfiguration of UI сomponents
This topic discusses the XML declaration of UI components.
About the layout configuration file and UI component declaration
Every module that has view representation contains the directory named
layout. In this directory, the
.xml declarations of the pages are stored. These
.xml declarations are, in fact, the pages’ markup.
In a typical Magento
.xml layout file we see a
<title/> node with the name of the page, and sometimes links to CSS and JS files. There are other nodes as well, the most important for us now is the
<referenceContainer/> node. (The
name attribute in this node is responsible for the position of the container on the page.). Top-level UI components are declared in this node. All nested components are declared in the top-level components’ instances configuration files (not in the page layouts).
Example of a top-level UI component declaration:
A UI component is declared using the
<uiComponent/> node. The
name attribute in the
<uiComponent/> node references the XML configuration of the top-level UI component’s instance. This configuration is a separate
.xml file. It is stored in the
<module_dir>/view/<area>/ui_component/ directory. For example
About the top-level component configuration file
The instance configuration file name is the name of instance (
%instance_name%). The namespace of the names is global; meaning that if the file names in different modules are the same, they are merged into a single configuration for the particular instance.
Following are the rules for the instance configuration files:
- The top node must have the name of one of the top-level UI components.
- The top node must contain a link to the XSD schema.
In the top node, there can be an
<argument/> node. The
<argument/> node contains the configuration for that top-level UI component. The
name attribute value must be
data. The child nodes of the
<argument> node will be the argument properties that will be passed in to the component.
The top node can have nested nodes. Every nested node is regarded as a separate UI component (i.e. the toolbar). For example, if you want your listing to have a toolbar, then the top node is for the listing and a nested node represents a toolbar. Nested nodes can also contain the
Example of a top-level configuration file
In the above example, within the top-level
<form> node the
<fieldset> node is nested. It declares the Fieldset UI component.
name attribute value must be a unique among the other components on the same hierarchical level of the same parent node. Look at the
<argument> node which
name attribute has
data value. The child nodes of this node are the arguments that will be passed in to the component.
All other child nodes are declared as items.
<item name="config"> ...</item> contains the children nodes that describe the configuration of the current UI component. Please note that although configuration for all components is different, there are base properties that are mostly the same for different components. For example, we can use
<item name="component">...</item> to define which JS file will be used as the Model for the Fieldset UI component in the above example. Reference to this JS file can be either be the full path to this file or the alias which is defined in
In our example, the
<item name="component">...</item> node within
<fieldset> is omitted, because this property of the Fieldset UI component is already defined in
In this example we showed only a small part of the possible configuration.
The default configuration of a UI component is declared in one of the following ways:
- inside the UI component itself, in the
- in the
- in both places, in which case the configurations merge (the UI component
.jsfile has priority).
In the above example, the Fieldset UI component uses a merged configuration from both the
definition.xml file and from the UI componenet’s
For more information about the configuration flow, refer to the Configuration Flow of UI Components topic.