Detail Guide to Create Magento 2 System.xml Configuration

The system.xml is a configuration file which is used to create configuration fields in Magento 2 System Configuration. You will need this if your module has some settings which the admin needs to set. You can go to Store -> Setting -> Configuration to check how it look like.

To Create system.xml

Step 1: Create System.xml

The magento 2 system configuration page is divided logically in few parts: Tabs, Sections, Groups, Fields. Please check this images to understand about this:

magento 2 system configuration

So let’s start to create a simple configuration for the simple Module Hello World. The system.xml is located in etc/adminhtml folder of the module, we will create it a new Tab for our vendor “Mageplaza”, a new Section for our module Hello World, a Group to contain some simple fields: enable module and text.

File: app/code/Mageplaza/HelloWorld/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="mageplaza" translate="label" sortOrder="10">
            <label>Mageplaza</label>
        </tab>
        <section id="helloworld" translate="label" sortOrder="130" showInDefault="1" showInWebsite="1" showInStore="1">
            <class>separator-top</class>
            <label>Hello World</label>
            <tab>mageplaza</tab>
            <resource>Mageplaza_HelloWorld::helloworld_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>Module Enable</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
                <field id="display_text" translate="label" type="text" sortOrder="1" showInDefault="1" showInWebsite="0" showInStore="0">
                    <label>Display Text</label>
                    <comment>This text will display on the frontend.</comment>
                </field>
            </group>
        </section>
    </system>
</config>

Checking this code, you will see how to create a Tab, Section, Group and Field. We will find more detail about each element:

  • The Tab element may have many sections and some main attributes and child:
    • Id attribute is the identify for this tab
    • sortOrder attribute will define the position of this tab.
    • Translate attribute let Magento know which title need to translate
    • Label element child is the text which will show as tab title.
  • 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. You can change the scope here

magento 2 system configuration

The section may have many group and some other child elements:

  • Class: this value will be added as class for this element. You should you it if you want to make-up this element.
  • Label: the text title of this element
  • Tab: this’s 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
  • Resource: defined the ACL rule which the admin user must have in order to access this configuration.
  • Group: This element may have many field and some attributes which is same as Sections.
  • Fields: is the main path of this page. It will save the data which we want to setting. In this element, we focus on the type attribute. It will define how the element is when display. It can be: text, select, file… In this example we create 2 fields with type select and text. 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 source_model.

Step 2: Set default value

Each field in system.xml after create will not have any value. When you call them, you will receive ‘null’ result. So for the module, we will need to set the default value for the field and you will call the value without go to config, set value and save it. This default value will be saved in config.xml which is located in etc folder. Let’s create it for this simple configuration:

File: app/code/Mageplaza/HelloWorld/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>
        <helloworld>
            <general>
                <enable>1</enable>
                <display_text>Hello World</display_text>
            </general>
        </helloworld>
    </default>
</config>

You can put the path to the field in the <default> element to set value default for it. The format is:

<default>
    <section>
        <group>
            <field>{value}</field>
        </group>
    </section>
</default>

Step 3: Flush Magento Cache

Now, please refresh your cache and see the result:

general configuration admin

Note that, if you might get an Error 404 Page Not Found first time, just logout and login again to fix this.

Step 4: Get value from configuration

First all of let’s save value and flush cache, then you can get saved value from database.

In the system.xml, we have added 2 fields: enable and display_text. So the path should be:

  • helloworld/general/enable
  • helloworld/general/display_text

4.1 Simple calling:

$this->scopeConfig->getValue('helloworld/general/enable', \Magento\Store\Model\ScopeInterface::SCOPE_STORE);
$this->scopeConfig->getValue('helloworld/general/display_text', \Magento\Store\Model\ScopeInterface::SCOPE_STORE);

4.2 Create a helper file (standard)

Create file: app/code/Mageplaza/HelloWorld/Helper/Data.php

<?php

namespace Mageplaza\HelloWorld\Helper;

use Magento\Framework\App\Helper\AbstractHelper;
use Magento\Store\Model\ScopeInterface;

class Data extends AbstractHelper
{

	const XML_PATH_HELLOWORLD = 'helloworld/';

	public function getConfigValue($field, $storeId = null)
	{
		return $this->scopeConfig->getValue(
			$field, ScopeInterface::SCOPE_STORE, $storeId
		);
	}

	public function getGeneralConfig($code, $storeId = null)
	{

		return $this->getConfigValue(self::XML_PATH_HELLOWORLD .'general/'. $code, $storeId);
	}

}

Now, we try get it in controller.

File: app/code/Mageplaza/HelloWorld/Controller/Index/Config.php

<?php

namespace Mageplaza\HelloWorld\Controller\Index;

class Config extends \Magento\Framework\App\Action\Action
{

	protected $helperData;

	public function __construct(
		\Magento\Framework\App\Action\Context $context,
		\Mageplaza\HelloWorld\Helper\Data $helperData

	)
	{
		$this->helperData = $helperData;
		return parent::__construct($context);
	}

	public function execute()
	{

		// TODO: Implement execute() method.

		echo $this->helperData->getGeneralConfig('enable');
		echo $this->helperData->getGeneralConfig('display_text');
		exit();

	}
}

Please run php bin/magento cache:clean to clear cache and check the result.

display config

Related

Image Description
Vinh Jacker
With over a decade of experience crafting innovative tech solutions for ecommerce businesses built on Magento, Jacker is the mastermind behind our secure and well-functioned extensions. With his expertise in building user-friendly interfaces and robust back-end systems, Mageplaza was able to deliver exceptional Magento solutions and services for over 122K+ customers around the world.
Previous How to Create Magento 2 Block, Layout and Templates
Next How To Create Admin Menu In Magento 2
One Step Checkout for Magento 2 by Mageplaza

People also searched for

  • magento 2 system configuration 500 error
  • magento 2 system configuration tutorial
  • magento 2 system configuration table
  • magento 2 system configuration validation
  • magento 2 system configuration not working
  • magento 2 system configuration required field
  • magento 2 how to create system.xml configuration
  • magento 2 system configuration acl
  • magento 2 add system configuration option
  • magento 2 admin system configuration 404
  • magento 2 add admin system configuration
  • magento 2 system configuration blank
  • magento 2 system configuration button
  • magento 2 how can elements in system configuration be rendered with a custom template
  • magento 2 system configuration catalog
  • magento 2 configuration system cron
  • magento 2 create system configuration
  • magento 2 custom module system configuration
  • magento 2 system configuration design
  • magento 2 system configuration developer
  • magento 2 add field in system configuration
  • magento 2 system configuration general
  • magento 2 system configuration guide
  • magento 2 get system configuration value
  • magento 2 system configuration http 500
  • system configuration in magento 2
  • magento 2 grid in system configuration
  • magento 2 add item to system configuration
  • magento 2 add link to system configuration
  • magento 2 system configuration menu
  • magento 2 system configuration source model
  • magento 2 module system configuration
  • system.xml magento 2
  • magento 2 system xml
  • magento 2 system configuration
  • system.xml in magento 2
  • magento 2 add field to system configuration
  • magento 2 system configuration xml
  • magento 2 system.xml
  • config.xml in magento 2
  • 2.3.x, 2.4.x
x