Adding custom entries to admin system configuration

Hello, in this article we will cover how to add custom entries in existing system configuration located in Stores->Configuration.
We have already covered how to create Magento2 module, so here we will go straight to the point. Replace Inchoo/Test from entries in this article to your module name.
in etc/adminhtml/system.xml inside your module add the following entries:
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xs
<system>
<tab id="inchoo_custom_config" translate="label" sortOrder="100">
<label>Inchoo Custom Config Page</label>
</tab>
<section id="inchoo_entry_1" translate="label" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
<class>separator-top</class>
<label>Inchoo Config SubItem</label>
<tab>inchoo_custom_config</tab>
<resource>Inchoo_Test::config</resource>
<group id="general" translate="label" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="0">
<label>General Configuration</label>
<comment>This is example configuration page.</comment>
<field id="inchoo_text" translate="label" sortOrder="1" showInDefault="1" showInWebsite="0" showInStore="0">
<label>Text</label>
<comment>This is example comment.</comment>
</field>
<field id="inchoo_yesno" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="0">
<label>Is Enabled</label>
<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
</field>
<field id="inchoo_dropdown_custom" translate="label" type="select" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
<label>Inchoo Custom Dropdown</label>
<source_model>Inchoo\Test\Model\Config\Custom</source_model>
</field>
<field id="inchoo_dropdown_dependable" translate="label" type="select" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
<label>Inchoo Custom Dependable Dropdown</label>
<depends>
<field id="*/*/inchoo_yesno">1</field>
</depends>
<source_model>Inchoo\Test\Model\Config\Custom</source_model>
</field>
<field id="inchoo_multiselect" translate="label" type="multiselect" sortOrder="40" showInDefault="1" showInWebsite="0" showInStore="0" canRestore="1">
<label>Multiselect</label>
<source_model>Inchoo\Test\Model\Config\Multiselect</source_model>
</field>
</group>
</section>
</system>
</config>
Text entry
First field id=”inchoo_text” is a simple text field that will work simply by defining it in system.xml and does not require any source models.
Yesno entry
Field id=”inchoo_yesno” is classic yes/no dropdown as from Magento 1. Besides defining it in system.xml, no additional work is required for it to work.
In order for certain custom areas to work, we have to define source models stated in our system.xml. Although Magento will handle most of the work, we have to cover labels or logic (if needed) for our custom outputs.
Custom dropdown
For custom dropdown defined under id=”inchoo_dropdown_custom” we will add custom source model Inchoo\Test\Model\Config\Custom:
<?php
namespace Inchoo\Test\Model\Config;
class Custom implements \Magento\Framework\Option\ArrayInterface
{
/**
* @return array
*/
public function toOptionArray()
{
return [
['value' => 0, 'label' => __('First')],
['value' => 1, 'label' => __('Second')],
['value' => 2, 'label' => __('Third')],
['value' => 3, 'label' => __('Fourth')]
];
}
}
Depends tag
Next example id=”inchoo_dropdown_dependable” is the same as last one, but because we added depends tags in system.xml it will depend strictly on value of inchoo_yesno. This is part of system.xml that makes it dependable:
<depends>
<field id="*/*/inchoo_yesno">1</field>
</depends>
Custom Multiselect
In order to make custom multiselect id=”inchoo_multiselect” to work, we first have to define source model Inchoo\Test\Model\Config\Multiselect like this:
<php
namespace Inchoo\Test\Model\Config;
class Multiselect extends \Magento\Captcha\Model\Config\Form\AbstractForm
{
/**
* @var string
*/
protected $_configPath = 'inchoo/multiselect';
/**
* Returns options for form multiselect
*
* @return array
*/
public function toOptionArray()
{
$optionArray = [];
$backendConfig = $this->_config->getValue($this->_configPath, 'default');
if ($backendConfig) {
foreach ($backendConfig as $formName => $formConfig) {
if (!empty($formConfig['label'])) {
$optionArray[] = ['label' => $formConfig['label'], 'value' => $formName];
}
}
}
return $optionArray;
}
}
Next step is to define default multiselect values. Inside etc/config.xml add the following entries that will represent default values, also notice that config tree is made from string defined inside protected variable $_configPath defined earlier in Inchoo\Test\Model\Config\Multiselect:
<config>
<default>
<inchoo>
<multiselect>
<first_entry>
<label>First entry</label>
</first_entry>
<second_entry>
<label>Second entry</label>
</second_entry>
</multiselect>
</inchoo>
</default>
</config>
This is it, just make sure to flush cache and refresh. Enjoy!
20 comments
How can we display Image in System Configuration?
thank you so much dude
nice article 🙂
Great article, But it will be more helpful if you will provide how to access the save data on frontend.
dineshkashera,
– tree path to your stored variable, exactly as declared in system.xml / config.xml
First line of system.xml is incomplete. Other than that, informative thank you.
Is it possible to create extension configuration page without system.xml file? Somewhere from php, by extending some core class?
you have great artcles thank you Tomislav. I always check you
thanks
Thanks Tomislav 🙂
Thank you for sharing.
Thanks for this codes, very useful.
Thanks for this codes, very useful.
thanks, love this website
How to get the system configuration values in the phtml file of the same custom module.
Thanks for sharing some useful code in this blog. It worked after some sort time executing it.
Hi,
Is it possible to have text field that are translate?
Have a default option, per language, but still be editable by the user?
Hello,
I haven’t tried it, but translations should be done by handling language specific directories and files in themes, by following:
Magento 2 official guide
Regards
Nice I always check you this blog thanks Tomislav.
Thank you for sharing.
Hi Tomislav,
Thanks for sharing some useful code in this blog. It worked after some sort time executing it.