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:

AttributeDescriptionTypeRequired
idDefines the identifier that is used referencing the section.typeIdrequired
translateDefines the field that should be translatable. Provide label to make the label translatable.stringoptional
sortOrderDefines the sort order of the section. High numbers push the section to the bottom of the page; low numbers push the section to the top.floatoptional
classAdds a defined CSS class to the rendered tab HTML element.stringoptional

Tab node reference

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

NodeDescriptionType
labelDefines the label that is displayed in the frontend.string

Example: Create a tab

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

<?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:

AttributeDescriptionTypeRequired
idDefines the identifier that is used referencing the section.typeIdrequired
translateDefines the field that should be translatable. Provide label to make the label translatable.stringoptional
typeDefines the input type of the rendered HTML element. Defaults to text.stringoptional
sortOrderDefines the sort order of the section. High numbers will push the section to the bottom of the page; low numbers will push the section to the top.floatoptional
showInDefaultDefines whether the section is shown in the default configuration scope. Specify 1 to show the section and 0 to hide the section.intoptional
showInStoreDefines whether the section is shown on store level. Specify 1 to show the section and 0 to hide the section.intoptional
showInWebsiteDefines whether the section is shown on website level. Specify 1 to show the section and 0 to hide the section.intoptional
canRestoreDefines if the section can be restored to default.intoptional
advancedDeprecated since 100.0.2.booloptional
extendsBy providing an identifier of another section, the content of this node will extend the section that you referenced.stringoptional

Section node reference

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

NodeDescriptionType
labelDefines the label that is displayed in the frontend.string
classAdds a defined CSS class to the rendered section HTML element.string
tabReferences the associated tab. Expects the ID of the tab.typeTabId
header_cssNeither used nor evaluated at the time of this writing.string
resourceReferences an ACL resource to provide permission settings for this section.typeAclResourceId
groupDefine one or more subgroups.typeGroup
frontend_modelSpecifies a different frontend model to change the rendering and modify the output.typeModel
includeUsed to include additional system_include.xsd compatible files. Usually used to structure large system.xml files.includeType

Example: Create a section and assign it to a tab

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

<?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:

AttributeDescriptionTypeRequired
idDefines the identifier that is used referencing the group.typeIdrequired
translateDefines the fields that should be translatable. Provide label to make the label translatable. Multiple fields should be separated by a space.stringoptional
typeDefines the input type of the rendered HTML element. Defaults to text.stringoptional
sortOrderDefines the sort order of the section. High numbers will push the section to the bottom of the page; low numbers will push the section to the top.floatoptional
showInDefaultDefines whether the group is shown in the default configuration scope. Specify 1 to show the group and 0 to hide the group.intoptional
showInStoreDefines whether the group is shown on store level. Specify 1 to show the group and 0 to hide the group.intoptional
showInWebsiteDefines whether the group is shown on website level. Specify 1 to show the group and 0 to hide the group.intoptional
canRestoreDefines if the group can be restored to default.intoptional
advancedDeprecated since 100.0.2.booloptional
extendsBy providing an identifier of another group, the content of this node will extend the section that you referenced.stringoptional

Group node reference

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

NodeDescriptionType
labelDefines the label that is displayed in the frontend.string
fieldset_cssAdds one or more CSS classes to a group fieldset.string
frontend_modelSpecifies a different frontend model to change the rendering and modify the output.typeModel
clone_modelSpecifies a given model to clone fields.typeModel
clone_fieldsEnabled or disabled cloning of fields.int
help_urlNot extensible. See below.typeUrl
more_urlNot extensible. See below.typeUrl
demo_linkNot extensible. See below.typeUrl
commentAdds a comment below the group label. By using <![CDATA[//]]> HTML can be applied.string
hide_in_single_store_modeWhether the group should be visible in single store mode. 1 hides the group; 0 shows the group.int
fieldDefine one or more fields that should be available under this group.field
groupDefine one or more subgroups.unbounded
dependsCan be used to declare dependencies on other fields. Is used to show specific fields/groups only when a given field has a value of 1. This node expects a section/group/field-string.depends
attributeCustom attributes can be used by frontend models. Usually used to make a given frontend model more dynamic.attribute
includeUsed to include additional system_include.xsd compatible files. Usually used to structure large system.xml files.includeType
WARNING
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 group for a given section

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

<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.