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!