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.
As the configuration fields are only accessible through the backend web pages, the configuration file is stored in the etc/adminhtml
directory.
Create your own configuration options with the following step:
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>GenmatoSampleModelConfigSourceDemoList</source_model> </field> </group> </section> </system> </config>
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.
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 sectionstranslate
: 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 tabsclass
: This is the optional class name for your tabThe 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.
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 identifiertranslate
: 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 sectionsshowInDefault
: This shows sections in the default store configurationshowInWebsite
: This displays sections in the website configurationshowInStore
: This displays sections in the store configurationThe available elements in this configuration are as follows:
class
: This is the class used for the sectionheader_css
: This is the CSS class to use in the text header for the sectionlabel
: This is the text to display in the sectiontab
: This is the reference to the tab where the section should be addedresource
: This is the access control list (ACL) resource referenced, which is used to check whether the user logged in has access to the sectionIn 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 optiontype
: This is the field type (text in this case)sortOrder
: This is the numeric value used to sort the groupsshowInDefault
: This shows a group in the default store configurationshowInWebsite
: This shows a group in the website configurationshowInStore
: This shows a group in the store configurationEvery 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 grouptranslate
: 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 fieldtextarea
: Text area inputobscure
: Password inputselect
: Drop-down selectThis 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 groupshowInDefault
: This shows fields in the default store configurationshowInWebsite
: This shows fields in the website configurationshowInStore
: This shows fields in the store configurationThere are also some extra elements available to configure the field:
label
: This is the label, which shows in front of the input fieldcomment
: This is the comment shown below the input fieldtooltip
: This is the text shown when hovering the question markfrontend_class
: This is the class used for the fieldfrontend_model
: This is the custom frontend model (block) that will be used to render the input areabackend_model
: This is the backend model used when saving the data to process inserted valuessource_model
: This is the data source used for select and multiselect fieldsdepends
: 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.
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
<p><?php echo $this->getHeader();?></p>
18.218.171.212