Creating system configuration fields

In Magento, it is possible to store configuration values for global/website or store in the backend. These values can be used to store simple module settings such as API -keys, module enable/disable options, or any setting that you might require for your module. The data is stored in the core_config_data table.

Getting ready

As the configuration fields are only accessible through the backend web pages, the configuration file is stored in the etc/adminhtml directory.

How to do it…

Create your own configuration options with the following step:

Create the system configuration file:

etc/adminhtml/system.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
  <system>
    <section id="sample" translate="label" type="text" sortOrder="2000" showInDefault="1" showInWebsite="1" showInStore="1">
      <label>Sample Configuration</label>
      <tab>general</tab>
      <resource>Genmato_Sample::config_sample</resource>
      <group id="demo" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
        <label>Sample</label>
        <field id="header" translate="label" type="text" sortOrder="1" showInDefault="1" showInWebsite="1" showInStore="1">
          <label>Header Title</label>
        </field>
        <field id="selectsample" translate="label" type="select" sortOrder="2" showInDefault="1" showInWebsite="1" showInStore="1">
          <label>Sample Select</label>
          <source_model>Genmato\Sample\Model\Config\Source\DemoList</source_model>
        </field>
      </group>
    </section>
  </system>
</config>

How it works…

The Magento store configuration is divided in separate sections and contains multiple groups of configuration fields. Every section is assigned to a main tab that is displayed above the sections.

Creating a new tab

When the configuration options that you want to add can't fit in one of the existing tabs, it is possible to add your own through the system.xml file. For this, add the following to your system configuration file:

<tab id="<unique tab name>" translate="label" sortOrder="<sort order>" class="<class>">
  <label>[label]</label>
</tab>

In the configuration, you can use the following attributes:

id: This is a unique identifier for the tab, which is also used to reference to the tab in your sections
translate: This specifies the elements that need to be available for translation (in this case, only the label field is available)
sortOrder: This is the numeric value to use to sort the tabs
class: This is the optional class name for your tab

The label element is used as the visible name of the tab in the configuration; it is important to make it as descriptive as possible for customers to understand.

Creating a new section

Every section is shown below the tab referenced in the configuration. In every section, multiple groups can be configured that can hold multiple fields. Adding a new section can be done by adding the following to your system.xml file:

<section id="<unique_section_name>" translate="label" type="<text>" sortOrder="<sort order>" showInDefault="<0/1>" showInWebsite="<0/1>" showInStore="<0/1>">
  <class>[class]</class>
  <header_css>[header_css]</header_css>
  <label>[label]</label>
  <tab>[tab]</tab>
  <resource>[resource]</resource>
</section>

The attributes used are as follows:

id: This is the unique section identifier
translate: This specifies the elements that need to be available for translation (in this case, only the label field is available)
type: This is the type of field used (normally text)
sortOrder: This is the numeric value to use to sort the sections
showInDefault: This shows sections in the default store configuration
showInWebsite: This displays sections in the website configuration
showInStore: This displays sections in the store configuration

The available elements in this configuration are as follows:

class: This is the class used for the section
header_css: This is the CSS class to use in the text header for the section
label: This is the text to display in the section
tab: This is the reference to the tab where the section should be added
resource: This is the access control list (ACL) resource referenced, which is used to check whether the user logged in has access to the section

Creating a new group

In a section, it is possible to create multiple groups; they are displayed as separate fieldsets that can be expanded/collapsed and can hold one or multiple fields. To create a new group, add the following (in the section to hold the group) to the system.xml file:

<group id="<group_id>" translate="label" type="text" sortOrder="<sort order>" showInDefault="<0/1>" showInWebsite="<0/1>" showInStore="<0/1>">
  <label>[label]</label>
</group>

The attributes to configure a group are as follows:

id: This is the unique ID for the group (in the section)
translate: These are the fields that needs to be translated, in this case, only the label option
type: This is the field type (text in this case)
sortOrder: This is the numeric value used to sort the groups
showInDefault: This shows a group in the default store configuration
showInWebsite: This shows a group in the website configuration
showInStore: This shows a group in the store configuration

The label element is shown as the heading of the group.

Creating a new field

Every group can have one or multiple fields. In the database, the configuration is stored as a path build, <section>/<group>/<field>. A new config field can be one of the following types: text input, textarea, select, multiselect, or a custom data renderer. To add a field, add the following to a group:

<field id="<field_id>" translate="label" type="<type>" sortOrder="<sort order>" showInDefault="<0/1>" showInWebsite="<0/1>" showInStore="<0/1>">
  <label>[comment]</label>
  <comment>[comment]</comment>
</field>

The attributes used for the field configuration are as follows:

id: This is the unique ID of the field in the group
translate: These are the fields that need to be translated (can be the label, comment, tooltip, or hint elements)
type: This is the input type, which can be the following:
- text: Default text input field
- textarea: Text area input
- obscure: Password input
- select: Drop-down select
  This needs a source_model element to specify the available options to select.
multiselect: This is the multiple item select box. This needs a source_model element to specify the available options to select.
image: This is the image upload with a preview if the file is uploaded. This needs different backend_model (to store the uploaded file), upload_dir (to specify where to save the file), and base_url (path used to build the URL to access from the frontend) elements.
sortOrder: This is the numeric value used to sort the fields in the group
showInDefault: This shows fields in the default store configuration
showInWebsite: This shows fields in the website configuration
showInStore: This shows fields in the store configuration

There are also some extra elements available to configure the field:

label: This is the label, which shows in front of the input field
comment: This is the comment shown below the input field
tooltip: This is the text shown when hovering the question mark
frontend_class: This is the class used for the field
frontend_model: This is the custom frontend model (block) that will be used to render the input area
backend_model: This is the backend model used when saving the data to process inserted values
source_model: This is the data source used for select and multiselect fields
depends: This is the option to hide/show a field based on a value used by another field, for example:
```
<depends>
  <field id="[field_name_to_check]">[value_to show]</field>
</depends>
```
When [field_name_to_check] has the [value_to_show] value, the field will be visible, if it contains a different value, then the field is hidden for the user.

There's more…

To get the data stored in the sample/demo/header field, add the following to the template Block class in our template block:

Block/DemoList.php

/**
* Get Header from configuration value
* @return string
*/
public function getHeader()
{
  return $this->_scopeConfig->getValue('sample/demo/header', ScopeInterface::SCOPE_STORE);
}

The _scopeConfig class is injected through dependency injection (DI) into the Block class in the constructor and allows us to read data stored in the configuration.

Next, we want to display the data in our template by adding the following line at the top of the file:

view/frontend/templates/list.phtml