Magento 2 System Configuration Field Types

If you are looking for a simple way to store single values required for application functionality in Magento 2, system configuration is the right solution for you. Similar to Magento 1, you can find Magento 2 system configuration fields in the core_config_data database table. However, there is a bit different in the XML config files.

In this article, I will give you the instruction for adding custom system configuration settings in Magento 2. Let’s explore how it is done through the below steps!

Step 1: Declare ACL For The Config In Our Extension

<?xml version="1.0"?>
<!--
/**
 * Location: magento2_root/app/code/Vendorname/Extensionname/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="Vendorname_Extensionname::config" title="Extension config example" sortOrder="50" />
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

Step 2: Add Our Extension Config File

<?xml version="1.0"?>
<!--
/**
 * Location: magento2_root/app/code/Vendorname/Extensionname/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="example_tab" translate="label" sortOrder="1000">
            <label>Example tab config</label>
        </tab>
        <section id="example_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Example config section</label>
            <tab>example_tab</tab>
            <resource>Vendorname_Extensionname::config</resource>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General</label>
                <field id="dropdown_example" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Dropdown with custom source model example</label>
                    <source_model>Vendorname\Extensionname\Model\Config\Source\Custom</source_model>
                </field>
                <field id="text_example" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Text example</label>
                </field>
                <field id="logo" translate="label" type="image" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Image example (with a comment)</label>
                    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
                    <upload_dir config="system/filesystem/media" scope_info="1">logo</upload_dir>
                    <base_url type="media" scope_info="1">logo</base_url>
                    <comment><![CDATA[Allowed file types: jpeg, gif, png.]]></comment>
                </field>
                <field id="depends_example" translate="label" type="text" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Dependant text field example with validation</label>
                    <depends>
                        <field id="*/*/dropdown_example">1</field>
                    </depends>
                    <validate>validate-no-empty</validate>
                </field>
                <field id="textarea_example" translate="label" type="textarea" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Textarea example</label>
                </field>
            </group>
        </section>
    </system>
</config>

Step 3: Add Custom Config Tab “Example tab config” And One Group Of Config Fields Within

With system.xml file, we need to declare our tab:

<tab id="example_tab" translate="label" sortOrder="1000">
    <label>Example tab config</label>
</tab>

And, there is only one group of fields (<group id=”general”>) and acl relation (“” tag) in our config section that belongs to this tab (with “” tag).

<section id="example_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Example config section</label>
    <tab>example_tab</tab>
    <resource>Vendorname_Extensionname::config</resource>
    <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
        <label>General</label>
        ......................
    </group>
</section>

Now, let ‘s see how to configure the five fields in the Example config section!

The First Example Config

A dropdown with a custom source model is the our first field:

<field id="dropdown_example" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Dropdown with custom source model example</label>
    <source_model>Vendorname\Extensionname\Model\Config\Source\Custom</source_model>
</field>

Then, we need to create that source model:

<?php

//Location: magento2_root/app/code/Vendorname/Extensionname/Model/Config/Source/Custom.php
namespace Vendorname\Extensionname\Model\Config\Source;

class Custom implements \Magento\Framework\Option\ArrayInterface
{
    /**
     * @return array
     */
    public function toOptionArray()
    {

        return [
            ['value' => 0, 'label' => __('Zero')],
            ['value' => 1, 'label' => __('One')],
            ['value' => 2, 'label' => __('Two')],
        ];
    }
}

The Second Example Config

A simple text field is the second example congig.

<field id="text_example" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Text example</label>
</field>

The Third Example Config

A ready image file upload field is far more interesting field which is using s built-in nsckend model, and accepts an uploaf_dir param for life saving, Here is the comment example for it:

<field id="logo" translate="label" type="image" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Image example (with a comment)</label>
    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
    <upload_dir config="system/filesystem/media" scope_info="1">logo</upload_dir>
    <base_url type="media" scope_info="1">logo</base_url>
    <comment><![CDATA[Allowed file types: jpeg, gif, png.]]></comment>
</field>

The Fourth Example Config

This config will come up only when value 1 (with label “One”) is chosen in our example dropdown via “" tag.

<field id="depends_example" translate="label" type="text" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Dependant text field example with validation</label>
    <depends>
        <field id="*/*/dropdown_example">1</field>
    </depends>
    <validate>validate-no-empty</validate>
</field>

The Fifth Example Config

A simple textarea example is the last example config.

<field id="textarea_example" translate="label" type="textarea" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Textarea example</label>
</field>

Alright, you just go through the process of configuring some fields in Example config section in Magento 2. Now, it is time for you to put together everything mentioned above to take the view (Admin Panel > Stores > Configuration).

By assessing to magento2_root/app/code/Magento/Config/Model/Config/Source, you can easily find out most of the source models. Backend models are stored in magento2_root/app/code/Magento/Config/Model/Config/Backend.

You also should check possible validation classes in magento2_root/lib/web/mage/validation.js under the rule variable (e.g., alphanumeric, zip-range, validate-email, etc.)

List Field Types:

Magento 2 system configuration provides the following field types:

  • button
  • 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

Conclusion

Above are the detailed instructions for adding a custom Magento 2 system configuration. I hope that this post will be useful for you in growing your Magento 2 store. If you have any questions or want to give your opinion, feel free to leave a comment below! Scroll down for some related reading.

Image Description
Sam Nguyen
Sam is the CEO & co-founder of Mageplaza, a company established to support Magento merchants with different powerful tools and resources. Sam Nguyen is also the CEO & founder of Avada Commerce, an e-commerce solution provider headquartered in Singapore – aiming to support more than a million online businesses to grow and develop.
Previous Magento 2 REST API - Benefits & Implementation Guidelines
Next Magento 2 Add, Edit Or Delete Action
One Step Checkout for Magento 2 by Mageplaza
x