system.xml reference

The system.xml file allows you to manage the Magento system configuration. Use this topic as a general reference for the system.xml file. The system.xml file is located under etc/adminhtml/system.xml in a given Magento 2 extension.

The following code snippet shows the bare skeleton of the file:

1
2
3
4
5
6
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <!-- PLACE YOUR MODULE SPECIFIC CONFIGURATION HERE -->
    </system>
</config>

If you want instant *XSD validation in your IDE, you can run bin/magento dev:urn-catalog:generate [--ide IDE] [--] <path>.

Tabs // Sections // Groups // Fields

In the system.xml file, it is possible to define four different types of entities, which are related to each other. The following section describes the relationship between tabs, sections, groups, and fields. The following screenshot displays the Magento 2 System Configuration in the Admin backend. The red squares mark the different types that are defined in the system.xml file:

Tabs are used to split different configuration areas semantically. Each tab can contain one or more sections, which can also be referenced as submenus. A section contains one or more groups. Each group lists one or more fields. You can also use a group to add a general description for the following fields. As mentioned, each group can have one or more fields. Fields are the smallest entity in the system configuration context.

Tabs

A <tab>-Tag references to either an existing or a new tab in the system configuration.

Tab attribute reference

A <tab>-Tag can have the following attributes:

Tab node reference

A <tab>-Tag can have the following child:

Example: Create a new tab

The following code snippet demonstrates the creation of a new tab with example data.

1
2
3
4
5
6
7
8
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>
    </system>
</config>

The snippet above creates a new tab with the identifier A_UNIQUE_ID. As the translate-attribute is defined and references the label, the label-node is translatable. During the rendering process, the CSS class a-custom-css-class-to-style-this-tab will be applied on the HTML element that was created for this tab. The sortOrder-attribute with the value of 10 defines the position of the tab in the list of all tabs when rendered.

Sections

A <section>-Tag references to either an existing or a new section in the system configuration.

Section attribute reference

A <section>-Tag can have the following attributes:

Section node reference

A <section>-Tag can have the following children:

Example: Create a new section and assign it to a tab

The following code snippet demonstrates the basic usage of creating a new section.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>

        <section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
            <label>A meaningful section label</label>
            <tab>A_UNIQUE_ID</tab>
            <resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
        </section>
    </system>
</config>

The section described above defines the ID A_UNIQUE_SECTION_ID, is visible in the default config view and in a store context. The label-node is translatable. The section is associated to the tab with the ID A_UNIQUE_ID. The section can only be accessed by users that have the permissions defined in the ACL VENDOR_MODULE::path_to_the_acl_resource.

Groups

The <group>-Tag is used to group fields together.

Group attribute reference

A <group>-Tag can have the following attributes:

Group node reference

A <group>-Tag can have the following children:

The nodes more_url, demo_url and help_url are defined by a PayPal frontend model that is only used once. These nodes are not reusable.

Example: Create a new group for a given section

The following code snippet demonstrates the basic usage of creating a new group.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>

        <section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
            <label>A meaningful section label</label>
            <tab>A_UNIQUE_ID</tab>
            <resource>VENDOR_MODULE::path_to_the_acl_resource</resource>

            <group id="A_UNIQUE_GROUP_ID" translate="label comment" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
                <label>A meaningful group label</label>
                <comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>
                <!-- Add your fields here. -->
            </group>
        </section>
    </system>
</config>

The group described above defines the ID A_UNIQUE_GROUP_ID, is visible in the default config view and in a store context. Both, the label and the comment are marked as translatable.

Fields

The <field>-Tag is used inside of <group>-Tags to define specific configuration values.

Field attribute reference

A <field>-Tag can have the following attributes:

Field type reference

A <field>-Tag can have the following values for the type="" attribute:

It is also possible to create a custom field type. This is often done when a special button, with an action, is required. To do this requires two main elements:

• Creating a block in the adminhtml area
• Setting the type="" to the path to this block

The block itself requires, at a minimum, a __construct method and a getElementalHtml() method. The Magento_OfflineShipping is a simple example of a custom type.

For example, in the OfflineShipping module, the Export button is defined in Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export and the field definition looks like:

1
2
3
<field id="export" translate="label" type="Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export" sortOrder="5" showInDefault="0" showInWebsite="1" showInStore="0">
    <label>Export</label>
</field>

Field node reference

A <field>-Tag can have the following children:

The nodes more_url, demo_url, requires and options are defined by a different core payment model and are only used once. These nodes are not reusable.

Example: Create two fields in a given group

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>

        <section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
            <label>A meaningful section label</label>
            <tab>A_UNIQUE_ID</tab>
            <resource>VENDOR_MODULE::path_to_the_acl_resource</resource>

            <group id="A_UNIQUE_GROUP_ID" translate="label" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
                <label>A meaningful group label</label>
                <comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>

                <field id="A_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="select">
                    <label>Feature Flag Example</label>
                    <comment>This field is an example for a basic yes or no select.</comment>
                    <tooltip>Usually these kinds of fields are used to enable or disable a given feature. Other fields might be dependent to this and will only appear if this field is set to yes.</tooltip>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>

                <field id="ANOTHER_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="text">
                    <label>A meaningful field label</label>
                    <comment>A descriptive text explaining this configuration field.</comment>
                    <tooltip>Another possible frontend element that also can be used to describe the meaning of this field. Will be displayed as a small icon beside the field.</tooltip>
                    <validate>required-entry no-whitespace</validate> <!-- Field is required and must not contain any whitespace. -->
                    <if_module_enabled>VENDOR_MODULE</if_module_enabled>
                    <depends> <!-- This field will only be visible if the field with the id A_UNIQUE_FIELD_ID is set to value 1 -->
                        <field id="A_UNIQUE_FIELD_ID">1</field>
                    </depends>
                </field>
            </group>
        </section>
    </system>
</config>

The example above creates two fields, both visible/configurable in default and in store view. Both fields have a comment and a tooltip to describe their purpose to the user. The label-node is translatable. The field with the identifier ANOTHER_UNIQUE_FIELD_ID is visible when the given module in the if_module_enabled is enabled globally. The field also validates its value against the rules required-entry and no-whitespace. The field with the identifier A_UNIQUE_FIELD_ID defines a different source model which provides tha values Yes and No.

Common source models

The following source models are provided by the Magento 2 Core. In general, there are many more source models; the following list describes the most common ones. Be aware, that these source models need the field attribute type to be set to select in order to work properly.

Field Validation

A field can have one or more validator-classes assigned to make sure that the input of the user meets the requirements of the extension. Validation rules can be applied with the <validate>-Tag. The following example validates a field and adds several different validation rules.

1
2
3
<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
    <validate>required-entry validate-clean-url no-whitespace</validate>
</field>

The following validation rules are available: