Magento 2 backend system configuration

When you are creating a new module , but the requirement is for setting some configuration for magento 2 backend then you need a file which will describe the Magento 2 backend system configuration of our module that is system.xml file. Get the the tricks to create configuration field in magento 2 back-end System configuration field.

Magento 2 backend system configuration

Magento 2 backend system configuration option values are store in core_config_data table.

Generally magento 2 configuration divided into four parts as like as magento 1 How to create custom configuration fields for magento

Tab => Section => Group => Filed.

I have used VendorName_ComponentName as JRB_Customconfig. So VendorName: JRB and ComponentName: Customconfig

If we are creating our own custom section then we need to give permission to our section in admin by declaring ACL.

<?xml version="1.0"?>
<!--
/**
 * file dir: magento2_root/app/code/JRB/Customconfig/etc/acl.xml
 */
-->
<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="JRB_Customconfig::config" title="Custom Settings" sortOrder="50" />
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

<?xml version="1.0"?>

<!--

/**

* file dir: magento2_root/app/code/JRB/Customconfig/etc/acl.xml

-->

<acl>

</resource>

</resources>

</acl>

</config>

then after we can add our custom section in backend:

<?xml version="1.0"?>
<!--
/**
 * file dir: magento2_root/app/code/JRB/Customconfig/etc/adminhtml/system.xml
 */
-->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="my_custom_tab" translate="label" sortOrder="1000">
            <label>Custom tab</label>
        </tab>
        <section id="my_custom_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Custom section</label>
            <tab>my_custom_tab</tab>
            <resource>JRB_Customconfig::config</resource>
            <group id="my_custom_group" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Custom Group</label>
                <field id="my_custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom field</label>
		    <comment><![CDATA[Custom text field]]></comment>
                </field>
            </group>
        </section>
    </system>
</config>

<?xml version="1.0"?>

<!--

/**

* file dir: magento2_root/app/code/JRB/Customconfig/etc/adminhtml/system.xml

-->

<label>Custom tab</label>

</tab>

<label>Custom section</label>

<tab>my_custom_tab</tab>

<resource>JRB_Customconfig::config</resource>

<label>Custom Group</label>

<label>Custom field</label>

</field>

</group>

</section>

</system>

</config>

Tab:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="my_custom_tab" translate="label" sortOrder="1000">
            <label>Custom tab</label>
        </tab>

	.................
	.................

    </system>
</config>

<label>Custom tab</label>

</tab>

.................

</system>

</config>

Attributes used :

translate : it is used to translate the label text that is used for tab rendering.
sort_order : It describe the tab position with other tabs.
id : it is unique name to identify tab of configuration

Used Nodes:

label: it is the label text that is used for tab rendering.
section: contains the description of section that will be shown below.

Section :

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <section id="my_custom_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
		<label>Custom section</label>
		<tab>my_custom_tab</tab>
		<resource>JRB_Customconfig::config</resource>
		<group ......
		...........
		...........

        </section>
    </system>
</config>

<label>Custom section</label>

<tab>my_custom_tab</tab>

<resource>JRB_Customconfig::config</resource>

<group ......

...........

</section>

</system>

</config>

Attributes used :

translate : it is used to translate the label text that is used for section rendering.
sort_order : It describe the tab position with other section.
id : it is unique name to identify section of configuration under a specific tab
showInDefault: means this section will be shown when default value is selected in current configuration scope.
showInWebsite: means this section will be shown when a website is selected in current configuration scope.
showInStore: means this section will be shown store is selected in current configuration scope.

Used Nodes:

label: it is the label text that is used for section rendering.
tab: it is used to define the tab name under which this section will belongs.
resource: the defined resource name will be used to ACL through which we can give permission to our custom section
group: contains the description of group that will be shown below.

Group:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <section id="my_custom_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
            <group id="my_custom_group" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1">
                <label>Custom Group</label>
                <field ...............
		......................
		......................

            </group>
        </section>
    </system>
</config>

<label>Custom Group</label>

<field ...............

......................

</group>

</section>

</system>

</config>

Attributes used :

translate : it is used to translate the label text that is used for group rendering.
sort_order : It describe the tab position with other group.
id : it is unique name to identify group of configuration under specific section
showInDefault: means this section will be shown when default value is selected in current configuration scope.
showInWebsite: means this section will be shown when a website is selected in current configuration scope.

Used Nodes:

label: it is the label text that is used for group rendering.
field: contains the description of field that will be shown below.

Field:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
	......................
	......................
                <field id="my_custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
			<label>Custom field</label>
			<comment><![CDATA[Custom text field]]></comment>
			<validate>required-entry validate-email</validate>
                </field>
        ...................
	...................

    </system>
</config>

......................

<label>Custom field</label>

<validate>required-entry validate-email</validate>

</field>

...................

</system>

</config>

Attributes used :

type: type of field
translate : it is used to translate the label text that is used for field rendering.
sort_order : It describe the tab position with other tabs.
id : it is unique name to identify field of configuration under specific group
showInDefault: means this section will be shown when deafult value is selected in current configuration scope.
showInWebsite: means this section will be shown when a website is selected in current configuration scope.
showInStore: means this section will be shown store is selected in current configuration scope.

Used Nodes:

label: it is the label text that is used for field rendering.
comment: contains the description of field. validate: validate input filed of that form

Magento 2 backend system configuration provides below fields type:

checkbox,
checkboxes,
column,
date,
editablemultiselect,
editor,
fieldset,
file,
gallery,
hidden,
image,
imagefile,
label,
link,
multiline,
multiselect,
note,
obscure,
password,
radio,
radios,
reset,
select,
submit,
text,
textarea,
time

List of mostly used source models:

Magento\Config\Model\Config\Source\Admin\Page – returns list of all the items in Magento Admin menu
Magento\Config\Model\Config\Source\Date\Short – returns list of available short date formats
Magento\Config\Model\Config\Source\Email\Identity – returns list of email sending identities (General Contact, Sales Representative, etc)
Magento\Config\Model\Config\Source\Email\Template – returns list of transactional email templates
Magento\Config\Model\Config\Source\Email\Method – returns list of transactional email methods (Bcc,Separate Email)
Magento\Config\Model\Config\Source\Email\Smtpauth\Smtpauth – returns list of SMTP Authorization (NONE,PLAIN,LOGIN,CRAM-MD5)
Magento\Config\Model\Config\Source\Locale\Country – returns list of localized country names
Magento\Config\Model\Config\Source\Locale\Currency\All – returns list of all currency names
Magento\Config\Model\Config\Source\Locale\Currency – returns list of localized currency names
Magento\Config\Model\Config\Source\Locale\Timezone – returns list of localized timezone names
Magento\Config\Model\Config\Source\Locale\Weekdays – returns list of localized weekday names
Magento\Config\Model\Config\Source\Locale\Weekdaycodes – returns list of localized weekday codes
Magento\Config\Model\Config\Source\Image\Adapter – returns hash of image adapter codes and labels
Magento\Config\Model\Config\Source\Reports\Scope – returns scope filter(Website,Store,Store View)
Magento\Config\Model\Config\Source\Design\Robots – returns all roboto txt contents(‘INDEX, FOLLOW’,’NOINDEX, FOLLOW’,’INDEX, NOFOLLOW’,’NOINDEX, NOFOLLOW’)
Magento\Config\Model\Config\Source\Dev\Dbautoup – returns auto update texts (‘Always (during development)’,’Only Once (version upgrade)’,’Never (production)’)
Magento\Config\Model\Config\Source\Web\Protocol – returns http/https of URL(‘HTTP (unsecure)’,’HTTPS (SSL)’)
Magento\Config\Model\Config\Source\Web\Redirect – returns URL redirect types(‘No’,’Yes (302 Found)’,’Yes (301 Moved Permanently)’)
Magento\Config\Model\Config\Source\Website\OptionHash – returns websites array
Magento\Config\Model\Config\Source\Enabledisable – return list of two options (“Enable” and “Disable”)
Magento\Config\Model\Config\Source\Nooptreq – return list of three options for customer widget mandatory indetificator (“Not”, “Optional”, “Required”).
Magento\Config\Model\Config\Source\Locale – return list of all locale
Magento\Config\Model\Config\Source\Yesno – return boolean options (“Yes”, “No”)
Magento\Config\Model\Config\Source\Website – return list of available websites
Magento\Config\Model\Config\Source\Store – return list of available stores

Apart from above source model we can create our own source module by implementing \Magento\Framework\Option\ArrayInterface
File location: app/code/JRB/Customconfig/Model/Config/Source/Ownsource.php

<?php

namespace JRB\Customconfig\Model\Config\Source;

class Ownsource implements \Magento\Framework\Option\ArrayInterface
{ 
    /**
     * Return array of options of value-label pair
     *
     * @return array
     */
    public function toOptionArray()
    {
        return [
            'own_value' => 'Own Label',
            'own_value1' => 'Own Label one',
            'own_value2' => 'Own Label two',
        ];
    }
}

<?php

namespace JRB\Customconfig\Model\Config\Source;

class Ownsource implements \Magento\Framework\Option\ArrayInterface

{

/**

* Return array of options of value-label pair

* @return array

public function toOptionArray()

{

return [

'own_value' => 'Own Label',

'own_value1' => 'Own Label one',

'own_value2' => 'Own Label two',

];

}

above source model can be called through system.xml file.
File location: app/code/JRB/Customconfig/etc/adminhtml/system.xml

<field id="own_select" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="0">
    <label>Own source model</label>
    <source_model>JRB\Customconfig\Model\Config\Source\Ownsource</source_model>
</field>

<label>Own source model</label>

<source_model>JRB\Customconfig\Model\Config\Source\Ownsource</source_model>

</field>

some of concepts needs to know:

Depends field :

<field id="my_custom_yesno" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Yes/No field (depends option)</label>
    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
    <comment><![CDATA[Yes showing text box.!]]></comment>
</field>

<label>Yes/No field (depends option)</label>

<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>

</field>

<field id="my_custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Text box depends</label>
    <depends>
        <field id="my_custom_yesno">1</field>
    </depends>
</field>

<label>Text box depends</label>

</depends>

</field>

Grouping groups:

<group id="mycustom_group_one" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1">
    <label>My Custom Group</label>
    <group id="mycustom_group_two" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1">
        <label>Mycustom Group Two</label>
        <field id="my_custom_field" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Custom field</label>
	    <comment><![CDATA[Custom text field]]></comment>
        </field>
    </group>
</group>

<label>My Custom Group</label>

<label>Mycustom Group Two</label>

<label>Custom field</label>

</field>

</group>

Image Upload:

<field id="mycustom_image" type="image" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>My custom image</label>
    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
    <upload_dir config="system/filesystem/media" scope_info="1">catalog/product/custom_image</upload_dir>
    <base_url type="media" scope_info="1">catalog/product/custom_image</base_url>
</field>

<label>My custom image</label>

<backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>

<upload_dir config="system/filesystem/media" scope_info="1">catalog/product/custom_image</upload_dir>

<base_url type="media" scope_info="1">catalog/product/custom_image</base_url>

</field>

Most of available source models : Magento\Config\Model\Config\Source\*
Most of available backend models : Magento\Config\Model\Config\Backend\*
Most of available validation classes : lib/web/mage/validation.js

Thanks for visiting this article, hope you understand this article (‘Magento 2 backend system configuration’).

Magento 2 backend system configuration