Magento 2 How to Create System.xml Admin Configuration

The system.xml is a admin configuration file which is used to create configuration fields in Magento 2 admin system configuration.

If you want to create some admin setting for your custom module, you need to create this file in following location:
File Path: app/code/Namespace/Modulename/etc/adminhtml/system.xml

And then you can go to Admin -> Store -> Setting -> Configuration to check those settings.

Now let's create the simple module which will elaborate the use of system.xml.

The Magento 2 system configuration page is divided logically in few parts: Tabs, Sections, Groups, Fields.

We need to follow the given steps to create and use the custom configuration we created:

Step 1: Create the module registration file as registration.php.

Location: app/code/Magemeta/Config/registration.php

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Magemeta_Config',
    __DIR__
);

Location: app/code/Magemeta/Config/etc/module.xml 

<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Magemeta_Config" setup_version="1.0.0"></module>
</config>

Location: app/code/Magemeta/Config/composer.json 
{
    "name": "magemeta/module-config",
    "description": "This module is used to create system configuration in admin and will explain how to use it",
    "type": "magento2-module",
    "license": "OSL-3.0",
    "authors": [
        {
            "email": "info@magemeta.com",
            "name": "magemeta"
        }
    ],
    "minimum-stability": "dev",
    "require": {},
    "autoload": {
        "files": [
            "registration.php"
        ],
        "psr-4": {
            "Magemeta\\Config\\": ""
        }
    }
}

Step 2:  Create a system.xml file in following location to create admin custom configuration.

Location: app/code/Magemeta/Config/etc/adminhtml/system.xml

<?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="magemeta" translate="label" sortOrder="10">
            <label>Magemeta</label>
        </tab>
        <section id="test" translate="label" sortOrder="130" showInDefault="1" showInWebsite="1" showInStore="1">
            <class>separator-top</class>
            <label>Magemeta Section</label>
            <tab>magemeta</tab>
            <resource>Magemeta_Config::test_config</resource>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="0">
                <label>General Configuration</label>
                <field id="enable" translate="label" type="select" sortOrder="1" showInDefault="1" showInWebsite="0" showInStore="0">
                    <label>Enable Module</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
                <field id="test_message" translate="label" type="text" sortOrder="1" showInDefault="1" showInWebsite="0" showInStore="0">
                    <label>Custom Text Message</label>
                    <comment>This custom text message will display on the frontend.</comment>
                </field>
            </group>
        </section>
    </system>
</config>

In above system.xml code piece, you will see how to create a Tab, Section, Group and Field. Please find more details about each element given below: 
The Tab element may have many sections and some main attributes and child:
a) Id attribute is the identify for this tab
b) sortOrder attribute will define the position of this tab.
c) Translate attribute let Magento know which title need to translate.
d) Label element child is the text which will show as tab title.
e) The Section element will have id, sortOrder, translate attributes like the Tab element.

Some other attributes (showInDefault, showInWebsite, showInStore) will decide this element will be show on each scope or not.
The section can have many groups and many other child elements as given below:
a) Label: The text title of this element.
b) Class: This value will be added as class for this element. You should use it if you want to create this element.
c) Tab: This is a tab id. This tab element will let Magento know the tab which this section is belong to. This section will be placed under that tab.
d) Resource: Defined the ACL rule which the admin user must have in order to access this configuration.
e) Group: This element may have many field and some attributes which is same as Sections.
f) Fields: This is the main path of this page. It will save the data in which we want to setting. In this element, we focus on the "type" attribute. It will define how the element is getting displayed. It can be: text, select, file or etc.
In above example, we create two fields with type text and select. With each type, we will define the child element for the field to make it work as we want.
For example, with the type select/multiselect you must define the child element as "source_model".

Step 3: Setting default values for custom configuration with the help of config.xml in the following location:

Location: app/code/Magemeta/Config/etc/config.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
    <default>
        <test>
            <general>
                <enable>1</enable>
                <test_message>This is a test message</test_message>
            </general>
        </test>
    </default>
</config>

Step 4: You need to clear the Magento cache now to get the configuration changes which will be visible in admin -> store -> configuration -> Magemeta location.
Just for your info, if you get any error like "Page Not Found" for the first time, make sure you logout and login again to fix this issue.

Step 5: Using or Accessing these custom configuration values: To use these config values, here we are creating a helper where we will fetch those system configurations and will use further as per need.

Location: app/code/Magemeta/Config/Helper/Data.php

<?php
namespace Magemeta\Config\Helper;

use Magento\Framework\App\Helper\AbstractHelper;
use Magento\Store\Model\ScopeInterface;
class Data extends AbstractHelper {
    public function getCustomConfiguration($field, $storeId = null) {
        return $this->scopeConfig->getValue( $field, ScopeInterface::SCOPE_STORE, $storeId );
    }
}
?>

You can access those helper methods as below in .phtml template files:

<?php echo $this->helper('Magemeta\Config\Helper\Data')->getCustomConfiguration('test/general/enable/');?>

<?php echo $this->helper('Magemeta\Config\Helper\Data')->getCustomConfiguration('test/general/test_message/'); ?>

Hope this helps you guys!

 

Leave a Reply