Magento 2

Magento 2 Field Types In System.xml: Your Cheat Sheet

Magento 2 field types are essential components of the system configuration, which allows you to control the functionality and behavior of your Magento store1. In this blog post, we will provide you with a cheat sheet for Magento 2 field types in system.xml, explaining their purpose, nature, and examples. We will also show you how to customize and create new field types for your specific needs. Whether you are a beginner or an expert, this blog post will help you master Magento 2 field types and optimize your store’s configuration

Introduction

 What is Magento 2 System Configuration?

Magento 2 System Configuration is a set of options that allows you to control the functionality and behavior of your Magento store. Located under Stores > Configuration in the Magento Admin, it provides a user-friendly interface to manage settings related to your store, such as general setup, currency, payment methods, shipping methods, and more. Each option in the System Configuration corresponds to a value stored in the core_config_data table in the Magento database.

Why Understanding Field Types Matters

Field Types

Each option in the System Configuration is represented by a field. These fields can be of different types – text field, dropdown, multiselect, etc., each serving a unique purpose. Understanding these field types is crucial as it determines the kind of data you can input and how it is stored and retrieved. For instance, a text field allows you to input a string of text, while a dropdown lets you select one option from a list. By understanding field types, you can effectively manage and optimize your store’s configuration.

Basic Magento 2 Field Types

In this section, we will explore the basic field types in Magento 2 System Configuration, each with an example code snippet.

Text

A simple input for text values.

Example:

XML
<field id="store_name" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Name</label>
</field>

Textarea

A multi-line text input for longer descriptions or content.

Example:

XML
<field id="store_description" translate="label" type="textarea" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Description</label>
</field>

Password

Securely stores sensitive information like passwords.

Example:

XML
<field id="admin_password" translate="label" type="password" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Admin Password</label>
</field>

Checkbox

A single option for true/false values.

Example:

XML
<field id="enable_feature" translate="label" type="checkbox" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Enable Feature</label>
</field>

Checkboxes

Multiple selection options for various choices.

Example:

XML
<field id="payment_methods" translate="label" type="checkboxes" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Payment Methods</label>
    <source_model>Vendor\Module\Model\Config\Source\PaymentMethods</source_model>
</field>

Radio

Single selection from a limited set of options.

Example:

XML
<field id="default_currency" translate="label" type="radio" sortOrder="60" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Default Currency</label>
    <source_model>Magento\Config\Model\Config\Source\Locale\Currency</source_model>
</field>

Radios

Multiple selection from a limited set of options.

Example:

XML
<field id="shipping_methods" translate="label" type="radios" sortOrder="70" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Shipping Methods</label>
    <source_model>Vendor\Module\Model\Config\Source\ShippingMethods</source_model>
</field>

Select

Dropdown menu for choosing from pre-defined options.

Example:

XML
<field id="default_country" translate="label" type="select" sortOrder="80" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Default Country</label>
    <source_model>Magento\Config\Model\Config\Source\Locale\Country</source_model>
</field>

Multiselect

Dropdown menu for selecting multiple options.

Example:

XML
<field id="product_categories" translate="label" type="multiselect" sortOrder="90" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Product Categories</label>
    <source_model>Magento\Catalog\Model\Category\Attribute\Source\Page</source_model>
</field>

Date

Date picker for entering specific dates.

Example:

XML
<field id="sale_start_date" translate="label" type="date" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Sale Start Date</label>
</field>

Time

Time picker for entering specific times.

Example:

XML
<field id="store_opening_time" translate="label" type="time" sortOrder="110" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Opening Time</label>
</field>

File

File upload for uploading images, documents, or other files.

Example:

XML
<field id="store_logo" translate="label" type="file" sortOrder="120" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Logo</label>
    <backend_model>Magento\Config\Model\Config\Backend\File</backend_model>
    <upload_dir config="system/filesystem/media" scope_info="1">logo</upload_dir>
</field>

Image

Image upload specifically for uploading images.

Example:

XML
<field id="store_banner" translate="label" type="image" sortOrder="130" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Banner</label>
    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
    <upload_dir config="system/filesystem/media" scope_info="1">banner</upload_dir>
</field>

Imagefile

Alternative image upload option for more control.

Example:

XML
<field id="store_icon" translate="label" type="imagefile" sortOrder="140" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Icon</label>
    <backend_model>Vendor\Module\Model\Config\Backend\ImageFile</backend_model>
    <upload_dir config="system/filesystem/media" scope_info="1">icon</upload_dir>
</field>

Please note that the source_model and backend_model in the examples need to be replaced with your actual models. Also, the upload_dir paths are just examples and should be updated according to your directory structure.

Advanced Magento 2 Field Types

In this section, we will explore the advanced field types in Magento 2 System Configuration, each with an example code snippet.

Multiline

Similar to textarea but with formatting options.

Example:

XML
<field id="store_address" translate="label" type="multiline" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Address</label>
    <line_count>3</line_count>
</field>

Editor

Rich text editor for creating complex content with formatting.

Example:

XML
<field id="store_description" translate="label" type="editor" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Description</label>
    <frontend_model>Magento\Config\Block\System\Config\Form\Field\Editor</frontend_model>
</field>

Button

Triggers actions like saving configuration or performing tasks.

Example:

XML
<field id="save_config" translate="label" type="button" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Save Configuration</label>
    <frontend_model>Magento\Config\Block\System\Config\Form\Field\Button</frontend_model>
</field>

External or internal link to other pages or resources.

Example:

XML
<field id="documentation_link" translate="label" type="link" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Documentation Link</label>
    <frontend_model>Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Link</frontend_model>
</field>

Note

Informative text displayed to users.

Example:

XML
<field id="note" translate="label" type="note" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Note</label>
    <frontend_model>Magento\Config\Block\System\Config\Form\Field\Note</frontend_model>
</field>

 Hidden

Stores configuration values without user input.

Example:

XML
<field id="hidden_field" translate="label" type="hidden" sortOrder="60" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Hidden Field</label>
</field>

Label

Displays static text for explanation or branding.

Example:

XML
<field id="label" translate="label" type="label" sortOrder="70" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Label</label>
</field>

Fieldset

Groups related fields for better organization.

Example:

XML
<group id="store_info" translate="label" type="fieldset" sortOrder="80" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Information</label>
</group>

Column

Displays multiple fields in a tabular format.

Example:

XML
<field id="store_hours" translate="label" type="column" sortOrder="90" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Store Hours</label>
    <frontend_model>Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Column</frontend_model>
</field>

Image gallery for managing multiple images.

Example:

XML
<field id="product_images" translate="label" type="gallery" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Product Images</label>
    <frontend_model>Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Gallery</frontend_model>
</field>

Please note that the frontend_model in the examples need to be replaced with your actual models. Also, the line_count in the multiline field example is just an example and should be updated according to your requirements.

Customizing Field Types

In this section, we will explore how to customize field types in Magento 2 System Configuration

Using Frontend Models to Modify Field Behavior

Frontend models provide a way to customize the behavior of fields in the Magento Admin. They are used to render fields in a specific way or add custom functionality. For example, you can use a frontend model to add a color picker to a text field.

Here’s an example of how to use a frontend model:

XML
<field id="background_color" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Background Color</label>
    <frontend_model>Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Color</frontend_model>
</field>

In this example, Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Color is a custom frontend model that renders the field as a color picker.

Creating New Field Types for Specific Needs

Sometimes, the built-in field types may not meet your specific needs. In such cases, you can create a new field type. This involves creating a new frontend model and possibly a backend model.

Here’s an example of how to create a new field type:

XML
<field id="custom_field" translate="label" type="custom" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Custom Field</label>
    <frontend_model>Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Custom</frontend_model>
    <backend_model>Vendor\Module\Model\Config\Backend\Custom</backend_model>
</field>

In this example, Vendor\Module\Block\Adminhtml\System\Config\Form\Field\Custom is a custom frontend model that renders the field in a custom way, and Vendor\Module\Model\Config\Backend\Custom is a custom backend model that handles the saving and loading of the field value.

Please note that creating new field types requires a good understanding of Magento’s system configuration and coding in PHP. Always test your custom field types thoroughly to ensure they work as expected.

Conclusion

This page is a cheat sheet for Magento 2 field types in system.xml, which are used to create and manage options in the System Configuration of a Magento store. The page explains the purpose, nature, and examples of various basic and advanced field types, such as text, textarea, password, checkbox, select, multiselect, date, time, file, image, editor, button, link, note, hidden, label, fieldset, column, and gallery. The page also shows how to customize field types using frontend models and backend models, and provides some tips and best practices for creating new field types. The page is intended for Magento developers who want to learn more about the system configuration and field types in Magento 2.

Magento 2 Developer Documentation on system.xml:

https://experienceleague.adobe.com/docs/

My aim was to make this blog post beneficial for you. If you have any doubts or questions, feel free to comment below.

Leave a Reply

Your email address will not be published. Required fields are marked *