How to add Magento 2 system configuration fields
Let’s find out how to add custom Magento 2 system configuration fields to the backend section of your module. The goal of this procedure is to enable store administrators to edit certain parts of your module. In Magento 1, you had to specify changes in etc/system.xml. As for Magento 2, you should utilize a system.xml file as well. However, there are some minor nuances discussed in this article.
This chapter is useful for people who:
- work on a Magento 2 module;
- need to add system configuration fields to the Magento 2 backend.
You can find system configuration fields in your database in the core_config_data table. All the necessary information is available in the same place where you can find it in Magento 1
The example from Magento 2 Blog explains how to add four new system configuration fields in Magento 2. The author of the article explores an importer module providing a detailed description of how to enable a store administrator to specify FTP connection details.
You need to add the following four elements:
- server – a field where an administrator can type a domain or an IP address of a remote server;
- user – an area to provide a valid FTP username;
- password – a field where a password that belongs to the user should be specified;
- path– a path necessary for the module to find import files.
From the perspective of the module, these Magento 2 system configuration fields are necessary to empower it to import all files under the specified path from an external server.
Note that all fields are:
- Simple text field;
- Each field has one exception;
- The password field supports passwords that are not plain text readable.
acl.xml
ACL is an access control list. As you might have already guessed from its name, acl.xml is a file where you provide different users with a separate access level. If you don’t want someone to change your modules system configurations, follow the steps below
- 1.Add a new acl.xml file to the module’s etc folder;
- 2.Define a role resource for the module’s system configuration.
The article from Magento2 Blog contains the following code example:
<? version="1.0"?>
<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="Magento_Backend::stores">
<resource id="Magento_Backend::stores_settings">
<resource id="Magento_Config::config">
<resource id="Example_Importer::config" title="Importer" sortOrder="50" />
</resource>
</resource>
</resource>
</resource>
</resources>
</acl>
Let’s explore the code above. By adding this snippet to your acl.xml file, you create a resource for Example_Importer. Replace Example_Importer with your module’s name using the following scheme: Vendorname_Extensionname. The file’s title is Importer. You can find it under System -> User Roles.
Now, click on the rule to see the following tree element in the “Role Resources” tab:
system.xml
After specifying different access levels, you can add Magento 2 system configuration fields. Create a new system.xml file under etc/adminhtml in the module’s directory. Below, you can see a code example utilized to create the four fields mentioned above:
<?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="mstage_tab" translate="label" sortOrder="1000">
<label>Example
</tab>
<section id="example_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
<label>Importer
<tab>mstage_tab
<resource>Mstage_Importer::config
<group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
<label>General
<field id="ftp_server" translate="label" type="text" sortOrder="20" showInDefault="1">
<label>Server
</field>
<field id="ftp_user" translate="label" type="text" sortOrder="20" showInDefault="1">
<label>User
</field>
<field id="ftp_password" translate="label" type="password" sortOrder="20" showInDefault="1">
<label>Password
</field>
<field id="ftp_dir" translate="label" type="text" sortOrder="20" showInDefault="1">
<label>Directory
</field>
</group>
</section>
</system>
</config>
It is also recommended to create a tab for your vendor name. Put all your modules there.
As for our example, it includes a submenu called Importer which contains a single general group. Leverage the group to hold all relevant FTP fields
Note that there is nothing complicated in the configuration of input fields. The only requirement is that they need a label. And a field tag has these attributes:
id – the field ID necessary to get the value by code. Define a useful name like in the case of variables;
type – the field type: “text” for simple text inputs and “password” for passwords;
showInDefault – set to 1 to add the field to the global scope. You can see the setting as a small hint in the backend;
showInWebsite – set to 1 to let an administrator change the field by a website;
showInStore – set to 1 to enable an administrator to change the field by a store view.
That’s all you need to know to add Magento 2 system configuration fields with different access levels. Now, let’s see how to get core config data programmatically in Magento 2.
Conclusion
In conclusion, adding system configuration fields in Magento 2 involves creating a custom module, defining the configuration fields in a system.xml file, setting up configuration scope if needed, creating a system configuration model to handle the values, and accessing the configuration values in your code or templates. By following these steps, you can extend the functionality of Magento 2 and customize the system configuration settings according to your specific requirements.