Magento 2

Master Magento 2 system.xml: Your Essential Guide 

Magento 2 system.xml is a powerful configuration file that allows you to customize the settings of your Magento store in the Admin panel1. In this blog, you will learn everything you need to know about Magento 2 system.xml, including its structure, elements, and usage. You will also discover how to set up different configurations for different stores and websites. Whether you are a beginner or an expert in Magento 2 development, this blog will help you master Magento 2 system.xml and create a better shopping experience for your customers.

Introduction

What is system.xml?

The system.xml file is a configuration file in Magento 2. It defines the structure of the system configuration in the Magento Admin. This file is used to create configuration fields, specify default values, and define how these fields interact with each other.

Where is it located?

The system.xml file is located in the etc directory of a module. For example, if you have a module named Vendor_Module, the system.xml file would be located at app/code/Vendor/Module/etc/adminhtml/system.xml.

Why is it important?

The Magento 2 system.xml file is crucial because it allows developers to add, remove, or modify settings available in the Magento Admin. These settings can control various aspects of your store, such as payment methods, shipping options, and more. By manipulating the system.xml file, developers can customize the Magento Admin to better suit the needs of the store.

Basic Structure of Magento 2 system.xml

The system.xml file in Magento 2 has a specific structure that must be followed. It consists of several elements, including the root element, modules, groups, and fields.

Magento 2's system.xml

Root Element

The root element of the system.xml file is the <config> tag. This tag encapsulates all the other elements in the file. It’s the starting and ending point of the file.

XML
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <!-- Other elements go here -->
</config>

Modules

Inside the <config> tag, we have the <system> tag, which contains one or more <section> tags. Each <section> tag represents a module in the Magento Admin

XML
<config>
    <system>
        <section id="module_name">
            <!-- Other elements go here -->
        </section>
    </system>
</config>

Groups

Within each <section> tag, there are one or more <group> tags. These represent different groups of settings within a module.

XML
<config>
    <system>
        <section id="module_name">
            <group id="group_name">
                <!-- Other elements go here -->
            </group>
        </section>
    </system>
</config>

Fields

Finally, within each <group> tag, there are one or more <field> tags. These represent individual settings within a group.

XML
<config>
    <system>
        <section id="module_name">
            <group id="group_name">
                <field id="field_name">
                    <!-- Other elements go here -->
                </field>
            </group>
        </section>
    </system>
</config>

Each field can have different attributes and child elements, such as <label>, <comment>, <frontend_type>, <source_model>, and <depends>.

That’s the basic structure of the system.xml file in Magento 2. Understanding this structure is crucial for customizing your Magento store to fit your business needs.

Commonly Used Elements in system.xml

Config

The <config> tag is the root element of the system.xml file. It encapsulates all the other elements in the file.

XML
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <!-- Other elements go here -->
</config>

System

The <system> tag contains one or more <section> tags. Each <section> tag represents a module in the Magento Admin panel.

XML
<config>
    <system>
        <!-- Other elements go here -->
    </system>
</config>

Tab

The <tab> tag is used to create a new tab in the Magento Admin panel. It should be defined in the acl.xml file of your module.

XML
<config>
    <system>
        <tab id="custom_tab" translate="label" sortOrder="10">
            <label>Custom Tab</label>
        </tab>
    </system>
</config>

Section

The <section> tag represents a module in the Magento Admin panel.

XML
<config>
    <system>
        <section id="custom_section" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Custom Section</label>
        </section>
    </system>
</config>

Group

The <group> tag represents different groups of settings within a module.

XML
<config>
    <system>
        <section>
            <group id="custom_group" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Custom Group</label>
            </group>
        </section>
    </system>
</config>

Field

The <field> tag represents individual settings within a group.

XML
<config>
    <system>
        <section>
            <group>
                <field id="custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Field</label>
                </field>
            </group>
        </section>
    </system>
</config>

Depends

The <depends> tag is used to create dependencies between fields. If a field depends on another field, it will only be visible if the field it depends on is set to a specific value.

XML
<config>
    <system>
        <section>
            <group>
                <field id="custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Field</label>
                    <depends>
                        <field id="other_field">1</field>
                    </depends>
                </field>
            </group>
        </section>
    </system>
</config>

Configuring Stores and Websites

Magento 2 allows you to set up different configurations for different stores and websites. This is particularly useful if you have multiple stores or websites that require different settings.

Setting up different configurations for different stores and websites

To set up different configurations for different stores and websites, you can use the system.xml file. Here’s an example:

XML
<config>
    <system>
        <section id="custom_section" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Custom Section</label>
            <group id="custom_group" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Custom Group</label>
                <field id="custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Field</label>
                </field>
            </group>
        </section>
    </system>
</config>

In this example, the showInDefault, showInWebsite, and showInStore attributes are set to 1 for the section, group, and field. This means that the custom section, group, and field will be shown in the default configuration, website configuration, and store configuration, respectively.

Using inheritance to simplify configuration

Magento 2 uses a system of inheritance to simplify configuration. This means that if a setting is not specified at a lower level (like a store view), it will inherit the setting from a higher level (like a website or the default configuration).

Here’s an example:

XML
<config>
    <system>
        <section id="custom_section" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Custom Section</label>
            <group id="custom_group" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Custom Group</label>
                <field id="custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="0">
                    <label>Custom Field</label>
                </field>
            </group>
        </section>
    </system>
</config>

In this example, the showInWebsite and showInStore attributes are set to 0 for the field. This means that the custom field will not be shown in the website configuration and store configuration. However, it will still be shown in the default configuration because the showInDefault attribute is set to 1.

Advanced Topics

Using ACL to control access to configuration settings

Access Control List (ACL) is a feature in Magento 2 that allows you to control access to certain parts of your store, including configuration settings. You can define ACL rules in the acl.xml file of your module.

Here’s an example of how to define an ACL rule:

XML
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Vendor_Module::config" title="Module Configuration" sortOrder="10" />
            </resource>
        </resources>
    </acl>
</config>

In this example, an ACL rule is defined for the module configuration (Vendor_Module::config). This means that only users with the appropriate permissions can access this configuration. We will deep dive into ACL in different blog. until then, stay tuned.

Defining custom validation rules for fields

Magento 2 allows you to define custom validation rules for fields in the system.xml file. You can do this by adding a <validate> tag to the field.

Here’s an example:

XML
<config>
    <system>
        <section>
            <group>
                <field id="custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Field</label>
                    <validate>validate-number</validate>
                </field>
            </group>
        </section>
    </system>
</config>

In this example, a validation rule is defined for the custom field. The validate-number rule ensures that the value entered in the field is a valid number.

Conclusion

The blog is a comprehensive guide on how to use the system.xml file in Magento 2 to customize the system configuration in the Magento Admin panel1. It covers the basic structure, commonly used elements, and advanced topics of the system.xml file. It also explains how to set up different configurations for different stores and websites, how to use ACL to control access to configuration settings, and how to define custom validation rules for fields. The blog is useful for Magento 2 developers who want to learn how to create and modify configuration settings for their modules.

To deepen your understanding, check out these valuable resources:

I hope this blog post has been of assistance to you. If you have any queries, please don’t hesitate to comment.

Leave a Reply

Your email address will not be published. Required fields are marked *